blocked

v0.10.0

blocked

blocked v0.10.0 Blocked View Source

Usage

  1. Put require Blocked in your module to be able to use the exposed macro.
  2. Write Blocked.by(issue_reference, reason, do: ..., else: ...) wherever you have to apply a temporary fix.

Example:

defmodule Example do
  require Blocked

  def main do
    IO.puts("Hello, world!")
    Blocked.by("#42", "This code can be removed when the issue is closed") do
      hacky_workaround()
    end

    # The reason is optional
    Blocked.by("#69") do
      a_quick_fix()
    end

    # It is possible to indicate
    # the desired 'ideal' code as well, by passing an `else` block:
    Blocked.by("#1337") do
      ugly_fallback()
    else
      beautiful_progress()
    end

    # If the blockage is more general, you can also leave out the `do` block.
    Blocked.by("#65535", "This whole module can be rewritten once we're on the new Elixir version!")

    # Blocked supports many ways of referring to an issue
    Blocked.by("#13")
    Blocked.by("elixir#13")
    Blocked.by("elixir/13")
    Blocked.by("elixir-lang/elixir#13")
    Blocked.by("elixir-lang/elixir/13")
    Blocked.by("https://github.com/elixir-lang/elixir/issues/13")
  end
end

When will Blocked.by/3 run?

By default, the checks will only be performed inside Continuous Integration environments. (That is, any place where System.get_env("CI") is set). The reason for this default is that the checks perform HTTP requests to the GitHub-API, which will slow down compilation somewhat.

This can be overridden by altering the warn-field in the Blocked.Config for a particular environment.

What if I have a private GitHub-repository?

By default, Blocked will run with an unauthenticated GitHub-client. You can configure the client by specifying an API token (of an account that has access to the repository in question) in the Blocked.Config.

Supported Issue Reference patterns

  1. 123 or #123: issue number. Assumes that the isue is part of the current repository.
  2. reponame/123 or reponame#123: repository + issue number. Assumes that the repository is part of the same owner/organization as the current repository.
  3. owner/reponame/123 or owner/reponame#123: owner/organization name + repository + issue number.
  4. https://github.com/owner/reponame/issues/123: Full-blown URL to the page of the issue.

Automatic Repository Detection

We use the git remote get-url command to check for the remote URL of the current repository and attempt to extract the owner/organization and repository name from that. We check against the upstream remote (useful in a forked project), and the origin remote.

If your setup is different, you can configure the repository and owner name by specifying custom settings in the Blocked.Config.

Link to this section Summary

Functions

by(issue_reference, reason \\ nil, code_blocks \\ [])

Prints a compile-time warning whenever the GitHub issue issue_reference is closed.

Link to this section Functions

Link to this macro

by(issue_reference, reason \\ nil, code_blocks \\ [])

View Source (macro)

Specs

by(
  binary(),
  binary() | nil,
  [] | [{:do, do_block()}] | [do: do_block(), else: do_block()]
) :: do_block() | else_block()

Prints a compile-time warning whenever the GitHub issue issue_reference is closed.

This warning will contain the optional reason.

General usage 

Blocked.by(issue_reference, reason) do
  # hotfix code here
  # ...
else
  # ideal code here
  # ...
end

When the issue is open, will expand to the hotfix code in the do: ... block. This block can be used to indicate the code that is a 'temporary hotfix'. This block is optional (but recommended).

When the issue is closed, will expand to the ideal code in the else: ... block. This block can be used to indicate the desired code that could be used once the hotfix is no longer necessary. This block is optional.

If no else: ... is passed, we'll still expand to the do: ... block (since the hotfix should in that case work).

See the module-documentation for more information on what format issue-references are supported, and on when Blocked.by is (and is not) run.

Examples

Only issue-reference

Blocked.by("some-repo/10")

Blocked.by("some-other-repo#10")

Issue-reference and reason

Blocked.by("some-repo/10", "We need a special fetching function to support this.")

Issue-reference, wrapping code (This is the recommended usage.)

defmodule Foo do
  require Blocked

  def y_plus_x_squared(y, x) do
  Blocked.by("some-repo/10", "Until a `pow` function exists, fall back to multiplication.") do
      y + (x * x)
    else
      y + pow(x, 2)
    end
  end
end