Merge pull request #33 from ausimian/issue/24-castle-task-namespace

refactor!: rename mix forecastle.relup to mix castle.relup

Author: ausimian

AGENTS.md

@@ -664,7 +664,7 @@ around it composes instead:
 
 ## Relup generation and upgrade strategy
 
-`mix forecastle.relup` takes an upgrade strategy — `auto` by default, `--hot`,
+`mix castle.relup` takes an upgrade strategy — `auto` by default, `--hot`,
 or `--restart` — and it is a property of each transition in the relup rather
 than of the release, because that is what it is: a relup for release X carries
 one entry per from-version, and whether that particular edge can be hot has
@@ -886,7 +886,7 @@ changing the fixture.
 | --- | --- |
 | `lib/forecastle.ex` | Release step hooks (the whole of the build-time logic) |
 | `lib/mix/tasks/compile/appup.ex` | `:appup` compiler — evaluates the file named by the `:appup` project key and writes `<app>.appup` into `ebin` |
-| `lib/mix/tasks/forecastle.relup.ex` | `mix forecastle.relup` — chooses an upgrade strategy per transition, and writes the relup |
+| `lib/mix/tasks/castle.relup.ex` | `mix castle.relup` — chooses an upgrade strategy per transition, and writes the relup |
 | `priv/castle.sh.eex` | EEx template for `bin/castle`, the release management CLI |
 | `priv/env.sh.eex` | EEx template for the fragment appended to the release's `env.sh` |
 | `priv/start.sh.eex` | EEx template for `bin/start`, the inert program heart is handed |
@@ -923,7 +923,7 @@ directory to start from a clean slate.
 | `test/forecastle/castle_cli_test.exs` | `bin/castle` as a shell script, against a launcher stub that records its arguments |
 | `test/forecastle/env_script_test.exs` | The `env.sh` fragment as a shell script, sourced in a release-shaped directory with a launcher stub: the heart environment it leaves behind, and which provisional version each state of the two markers selects |
 | `test/forecastle/configuration_test.exs` | A release that names its own runtime configuration file and declares providers whose init arguments are not keyword lists — assembled, and booted through `bin/<name> eval` |
-| `test/forecastle/relup_test.exs` | `mix forecastle.relup` as a command, against three assembled releases: argument handling, exit status, and all three upgrade strategies |
+| `test/forecastle/relup_test.exs` | `mix castle.relup` as a command, against three assembled releases: argument handling, exit status, and all three upgrade strategies |
 | `test/forecastle/upgrade_test.exs` | Booting a release and hot-upgrading it, including the code path of an application the relup does not load, tagged `:e2e` |
 | `test/forecastle/restart_upgrade_test.exs` | The same shape through an emulator restart: the OS pid changes, an uncommitted release rolls back when killed, and a commit makes it what an ordinary start boots. Tagged `:e2e` |
 

README.md

@@ -10,7 +10,10 @@ upgrades. This includes:
   - Adding a `bin/castle` command for unpacking and installing releases, alongside
     the standard Mix launcher.
 
-Additionally, `Forecastle` ships with a appup compiler and a mix task for relup generation.
+Additionally, `Forecastle` ships with an appup compiler and a mix task for relup
+generation. Both are named for `Castle` rather than for the package that
+implements them - `mix castle.relup` and the `:appup` compiler - because where the
+build-time code lives is a packaging decision, and what a developer types is not.
 
 ## Installation
 
@@ -223,7 +226,7 @@ on, with nobody intervening. `bin/<release> version` reports that version too,
 because what it prints is the version *to be booted*; ask the running system if
 you want to know what is running.
 
-**Only the one-stage `restart_emulator` is supported.** `mix forecastle.relup`
+**Only the one-stage `restart_emulator` is supported.** `mix castle.relup`
 never generates the two-stage `restart_new_emulator` and refuses it wherever it
 finds one; see below.
 
@@ -277,12 +280,12 @@ build wrote stays where it is.
 
 ## Relup Generation
 
-Forecastle contains a mix task, `forecastle.relup`, that simplifies the generation of
-the relup file. Assuming you have two _unpacked_ releases e.g. `0.1.0` and `0.1.1` 
-and you wish to generate a relup between them:
+`Forecastle` provides the mix task `castle.relup`, which simplifies the generation
+of the relup file. Assuming you have two _unpacked_ releases e.g. `0.1.0` and
+`0.1.1` and you wish to generate a relup between them:
 
 ```shell
-> mix forecastle.relup --target myapp/releases/0.1.1/myapp --fromto myapp/releases/0.1.0/myapp
+> mix castle.relup --target myapp/releases/0.1.1/myapp --fromto myapp/releases/0.1.0/myapp
 ```
 
 If the generated file is in the project root, it will be copied during
@@ -314,13 +317,13 @@ not of either release, so it is chosen per relup:
 
 ```shell
 # auto: hot where it can be
-> mix forecastle.relup --target ... --fromto ...
+> mix castle.relup --target ... --fromto ...
 
 # require a hot upgrade, and fail rather than degrade
-> mix forecastle.relup --target ... --fromto ... --hot
+> mix castle.relup --target ... --fromto ... --hot
 
 # force a full emulator restart, with no appups at all
-> mix forecastle.relup --target ... --fromto ... --restart
+> mix castle.relup --target ... --fromto ... --restart
 ```
 
 `--hot` and `--restart` are mutually exclusive, and each may be given once.

RELEASE.md

@@ -104,7 +104,7 @@
   a launcher stub as well. A continuation that fails and rolls back on the way up
   belongs to `restart_new_emulator`, which is not supported; see *Known
   limitations*.
-- `mix forecastle.relup` now takes an upgrade strategy, because whether a
+- `mix castle.relup` now takes an upgrade strategy, because whether a
   transition can be hot is a property of the edge between two releases rather
   than of either release. `--hot` requires a genuine hot upgrade and fails,
   having written nothing, if the transition cannot be one - a missing appup
@@ -329,6 +329,19 @@
 
 ### Changed
 
+- **Breaking:** `mix forecastle.relup` is now `mix castle.relup`. The task is
+  still implemented in Forecastle and still ships with it; only the name has
+  changed. Where build-time code lives is a packaging decision and what the task
+  is called is a user-interface one, and making the two agree split the
+  vocabulary in half: an operator ran `bin/castle install` while a developer ran
+  `mix forecastle.relup`, against a package that is, by design, in nobody's
+  `mix.exs`. Both READMEs say to depend on `Castle`, so `castle.*` is the name
+  the user already thinks in. There is no compatibility alias — a shim for a
+  package documented as not taken directly is code maintained forever for a user
+  who does not exist — so rename the invocation in any build pipeline that calls
+  it. `mix compile.appup` is unaffected: it is named by its `:compilers` entry
+  rather than by a package.
+  ([forecastle#24](https://github.com/ausimian/forecastle/issues/24))
 - **Breaking:** Forecastle no longer touches configuration. It used to set
   `:runtime_config_path` to `false`, install a `Config.Reader` of its own,
   initialise every config provider itself and stash the results, and rename the
@@ -439,7 +452,7 @@
 - The Castle integration is installed by extending the release's `env.sh`
   rather than by replacing the launcher. An `env.sh` supplied through
   `rel/env.sh.eex` is preserved and runs first.
-- `mix forecastle.relup` with no strategy switch is now `auto`, which changes what
+- `mix castle.relup` with no strategy switch is now `auto`, which changes what
   an existing invocation does with some transitions. Case by case, against a task
   that simply asked `systools` for the relup:
 
@@ -476,7 +489,7 @@
   refuses an appup-supplied emulator restart that the old task packaged. What it
   is good for is a pipeline that wants the generation to fail rather than degrade.
   `--restart` is the way to get a relup out of the two changed cases.
-- A `mix forecastle.relup` run that fails now writes nothing at all. It used to
+- A `mix castle.relup` run that fails now writes nothing at all. It used to
   let `systools` write the relup and report afterwards, which was harmless while
   every refusal came from `systools` itself; the strategies add refusals that can
   only be made once a relup has been generated, so the file is now written by the
@@ -493,7 +506,7 @@
   relup empty or half a plan even though the run failed. A reader now sees the
   whole of one relup or the whole of the other, and a build that reads it while a
   generation is running cannot read a partial one.
-- `mix forecastle.relup` now requires at least one of `--fromto`, `--upfrom` or
+- `mix castle.relup` now requires at least one of `--fromto`, `--upfrom` or
   `--downto`. It used to accept none and write a relup with no transitions in it,
   which is not an upgrade plan and which `release_handler` can do nothing with.
 - Raised the minimum Elixir requirement to 1.18.
@@ -542,10 +555,10 @@
   Install's lost-connection check is isolated as a whole-line launcher
   diagnostic, so ordinary error copy cannot trigger the restart-confirmation
   path.
-- `mix forecastle.relup` failed with `:systools is not available` in projects
+- `mix castle.relup` failed with `:systools is not available` in projects
   that do not themselves depend on `:sasl`, because Elixir prunes unused OTP
   applications from the build's code path.
-- `mix forecastle.relup` exited 0 when it had generated nothing.
+- `mix castle.relup` exited 0 when it had generated nothing.
   `:systools.make_relup/4` reports ordinary failure by returning `:error`, and
   Mix does not turn what a task returns into an exit status, so a build
   pipeline could not tell that generation had failed. Nothing removes a relup
@@ -554,7 +567,7 @@
   says what `systools` could not do and fails. Warnings that `systools` used to
   print for itself - an ERTS version change among them - are passed on rather
   than swallowed.
-- `mix forecastle.relup --outdir` was accepted and then ignored, so the relup
+- `mix castle.relup --outdir` was accepted and then ignored, so the relup
   was written to the current directory regardless, overwriting any unrelated
   relup already there. The switch now decides where the file goes, and the
   directory has to exist. Post-assembly still copies the relup it finds in the
@@ -573,7 +586,7 @@
   build that was silently packaging the wrong plan will now stop instead —
   before assembly begins, so a rejected relup leaves no half-built release
   behind for a later build to stumble over.
-- `mix forecastle.relup` discarded arguments it did not recognise, so a
+- `mix castle.relup` discarded arguments it did not recognise, so a
   mistyped switch, or a path given without one, generated a relup between
   releases the caller had not named instead of reporting the mistake. Omitting
   `--target` raised a `KeyError` from the middle of the task. Both are now

lib/forecastle.ex

@@ -171,7 +171,7 @@ defmodule Forecastle do
   # Checked in `pre_assemble/1`, before Mix has created anything, so all that is
   # left here is to put the bytes that were checked into the release.
   # Re-emitted from the term that was checked rather than copied from the file
-  # again: `:file.consult/1` reopens the path, and a `mix forecastle.relup`
+  # again: `:file.consult/1` reopens the path, and a `mix castle.relup`
   # running alongside the build can replace it in between, so a second read is
   # not necessarily the bytes that were checked. The format is the one
   # `systools` writes and `release_handler` reads - a UTF-8 coding comment and
@@ -190,11 +190,11 @@ defmodule Forecastle do
     end
   end
 
-  # The relup is produced by a separate `mix forecastle.relup` run, so nothing
+  # The relup is produced by a separate `mix castle.relup` run, so nothing
   # about being here says it belongs to the release being assembled. Packaging
   # one for another version is worse than packaging none at all: nothing checks
   # it again, and `release_handler` applies it as this version's upgrade plan.
-  # `mix forecastle.relup --outdir` makes that reachable - generation succeeds
+  # `mix castle.relup --outdir` makes that reachable - generation succeeds
   # elsewhere and an older relup is left sitting here - and so does anything that
   # left a partial one behind: the task itself publishes by renaming a staging
   # file over the relup, and so cannot, but a copy or an editor interrupted

lib/mix/tasks/forecastle.relup.ex lib/mix/tasks/castle.relup.exlib/mix/tasks/forecastle.relup.ex renamed to lib/mix/tasks/castle.relup.ex

@@ -1,8 +1,11 @@
-defmodule Mix.Tasks.Forecastle.Relup do
+defmodule Mix.Tasks.Castle.Relup do
   @moduledoc """
   Generate a relup file between releases.
 
-  `mix forecastle.relup` will generate a relup between a `target` release and
+  This task is provided by `Forecastle`, Castle's build-time half, and named
+  `castle.*` like the rest of the tooling a developer runs.
+
+  `mix castle.relup` will generate a relup between a `target` release and
   any number of other releases. The paths specifed in the options should
   be the paths to `.rel` files (but without the .rel extension)
 
@@ -893,7 +896,7 @@ defmodule Mix.Tasks.Forecastle.Relup do
     end
   end
 
-  # Unique per run: two `mix forecastle.relup` invocations sharing an `--outdir`
+  # Unique per run: two `mix castle.relup` invocations sharing an `--outdir`
   # must not stage over each other, so the name carries both the OS process and a
   # counter within it. And unmistakable for a relup - a leading dot and a `.tmp`
   # suffix - because post-assembly reads the path `relup`, and a staging file

lib/mix/tasks/compile/appup.ex

@@ -2,6 +2,8 @@ defmodule Mix.Tasks.Compile.Appup do
   @moduledoc """
   Compiles appup files into the application's ebin folder.
 
+  This compiler is provided by `Forecastle`, Castle's build-time half.
+
   The `:appup` project key names a file, relative to the project file, that is
   evaluated for its value. It must not introduce top-level bindings. Whatever it
   returns is written to `<app>.appup` alongside the application's beams.

test/fixtures/sample/dep/mix.exs

@@ -34,7 +34,7 @@ defmodule SampleDep.MixProject do
 
   `SAMPLE_DEP_VSN` pins it independently of the sample's, so that the fixture
   can be assembled as a transition in which *only* project-owned applications
-  changed. `mix forecastle.relup`'s `auto` strategy makes a transition a restart
+  changed. `mix castle.relup`'s `auto` strategy makes a transition a restart
   when the version of an application the project does not own moved, and this
   application - a dependency of the sample - otherwise always moves with it.
   Unset, which is how every other suite builds the fixture, it moves in step as

test/forecastle/assembly_test.exs

@@ -573,7 +573,7 @@ defmodule Forecastle.AssemblyTest do
     end
 
     test "is refused when it is an upgrade plan for another version" do
-      # The relup comes from a separate `mix forecastle.relup` run, so a stale
+      # The relup comes from a separate `mix castle.relup` run, so a stale
       # one can be sitting here - `--outdir` sends a successful generation
       # somewhere else and leaves this one behind. Packaging it would hand
       # `release_handler` the wrong version's instructions.

test/forecastle/relup_test.exs

@@ -1,6 +1,6 @@
 defmodule Forecastle.RelupTest do
   @moduledoc """
-  Drives `mix forecastle.relup` against two really-assembled releases.
+  Drives `mix castle.relup` against two really-assembled releases.
 
   Generating a relup needs two releases on disk, each with its `.rel` file and
   the `.appup` that carries the upgrade instructions, so there is no smaller
@@ -34,7 +34,7 @@ defmodule Forecastle.RelupTest do
   use Forecastle.ReleaseCase
 
   alias Forecastle.Fixture
-  alias Mix.Tasks.Forecastle.Relup
+  alias Mix.Tasks.Castle.Relup
 
   @from "0.1.0"
   @to "0.1.1"
@@ -634,7 +634,7 @@ defmodule Forecastle.RelupTest do
     end
 
     test "does not collide with another run publishing into the same directory", ctx do
-      # The staging file is named per run for this: two `mix forecastle.relup`
+      # The staging file is named per run for this: two `mix castle.relup`
       # invocations sharing an --outdir must not stage into the same file, or one
       # could publish a relup that is partly the other's. Whichever wins the
       # rename, the file is one of them whole.
@@ -850,9 +850,9 @@ defmodule Forecastle.RelupTest do
 
   defp rel(release, vsn), do: Path.join(release, "releases/#{vsn}/sample")
 
-  defp relup(args, vsn), do: mix(["forecastle.relup" | args], env(vsn))
+  defp relup(args, vsn), do: mix(["castle.relup" | args], env(vsn))
 
-  defp relup!(args, vsn), do: mix!(["forecastle.relup" | args], env(vsn))
+  defp relup!(args, vsn), do: mix!(["castle.relup" | args], env(vsn))
 
   # The task builds nothing, but Mix still loads the project around it. Pointing
   # it at the build tree the target release was assembled in keeps it from

test/support/deployment.ex

@@ -44,11 +44,11 @@ defmodule Forecastle.Deployment do
     args = ["--target", rel_path(to, to_vsn), "--fromto", rel_path(from, from_vsn)]
 
     Fixture.mix!(
-      ["forecastle.relup" | args ++ extra_args],
+      ["castle.relup" | args ++ extra_args],
       [{"SAMPLE_VSN", to_vsn}, {"MIX_BUILD_ROOT", Path.join(workspace, "_build-#{to_vsn}")}]
     )
 
-    assert File.exists?(relup), "mix forecastle.relup did not produce a relup"
+    assert File.exists?(relup), "mix castle.relup did not produce a relup"
 
     # And that it is a plan between these two versions, not merely a file.
     contents = File.read!(relup)