Merge pull request #36 from ausimian/issue/9-readme-task-provenance

docs: document the build-time tasks as castle.*

Author: ausimian

AGENTS.md

@@ -1197,7 +1197,7 @@ which is precisely what `customize/1` exists to prevent. Mix validates `:steps`
 **It changes exactly one option.** What a consumer still has to declare by hand
 is listed in the `@doc`, because the alternative is finding out from a failed
 upgrade: the `:appup` project key with `compilers: Mix.compilers() ++ [:appup]`,
-a relup from `mix forecastle.relup` left in the project root, and
+a relup from `mix castle.relup` left in the project root, and
 `include_executables_for: [:unix]` — Windows is unsupported and assembly only
 warns — plus the optional `rel/env.sh.eex`. `:steps` is the one option whose
 contents are Castle's business; the others are the project's own choices, and
@@ -1920,10 +1920,22 @@ the exit statuses `bin/castle` returns are asserted. None of it is measured here
   refuses: `mix docs` catches a broken *reference*, and nothing at all catches a
   true sentence that has stopped being true. Both are read against
   `Castle.Commands` by hand.
-- **The README is out of date.** It documents an `:appup` compiler and a
-  `mix castle.relup` task that moved to Forecastle in 0.3.0, the release
-  management commands it describes on `bin/<release>` now live on `bin/castle`,
-  and its integration section still tells a consumer to place
-  `Forecastle.pre_assemble/1` and `Forecastle.post_assemble/1` around
-  `:assemble` by hand, which is what `Castle.customize/1` replaced
-  ([#9](https://github.com/ausimian/castle/issues/9)).
+- **Nothing runs the README's build-time instructions the way a consumer would,
+  and the gap is narrower than "there is no test".** Forecastle's suite
+  exercises `mix castle.relup` and the `:appup` compiler thoroughly — but its
+  sample fixture takes Forecastle as a `path` dependency with `override: true`,
+  so what it establishes is that the implementations work, not the claim this
+  README actually makes: that depending on **Castle alone** is enough to get
+  them. Neither repository runs that flow, and the `override:` is deliberate
+  (Forecastle has to be testable without Castle's API), so it is not something
+  to fix by tidying the fixture.
+
+  That is not hypothetical. Closing
+  [#9](https://github.com/ausimian/castle/issues/9) documented
+  `mix castle.relup` here while `mix.lock` still pinned a Forecastle from before
+  [forecastle#24](https://github.com/ausimian/forecastle/issues/24) renamed it —
+  so a clean checkout honouring the committed lock had no such task, and the
+  whole suite stayed green. Advancing the pin is what made the documentation
+  true. Until a consumer-shaped fixture exists, the check is manual: read the
+  lock against Forecastle's task surface whenever either side of the pair
+  changes.

README.md

@@ -80,8 +80,10 @@ the launcher setup Castle needs.
 
 ## Appups and relups
 
-Write an appup for each application whose code changes during a hot upgrade.
-The appup file uses Erlang terms written in Elixir syntax:
+Write an appup for each application you own that has to be upgraded in place.
+Whether a given transition needs one depends on the strategy below and on which
+applications changed; `mix castle.relup` documents the rules. The appup file
+uses Erlang terms written in Elixir syntax:
 
 ```elixir
 {
@@ -98,7 +100,7 @@ The appup file uses Erlang terms written in Elixir syntax:
 Generate a relup between assembled releases:
 
 ```shell
-mix forecastle.relup \
+mix castle.relup \
   --target _build/prod/rel/my_app/releases/1.1.0/my_app \
   --fromto _build/prod/rel/my_app/releases/1.0.0/my_app
 ```
@@ -107,6 +109,14 @@ The task writes `relup` to the project root by default. Leave it there for the
 next release build to package. Use `--hot` to require a hot transition or
 `--restart` to force a one-stage emulator restart.
 
+`mix castle.relup` is implemented in Forecastle, which Castle brings in as a
+build-time dependency. It is named for Castle because that is the package a
+project depends on, and nothing has to be added to `deps` to get it.
+
+The appup compiler comes from Forecastle the same way, but is named for what it
+does rather than for either package: it stays `mix compile.appup`, reached
+through the `:compilers` list above. There is no `mix castle.appup`.
+
 ## Managing releases
 
 Build the new release, then copy `<name>-<vsn>.tar.gz` into the running

RELEASE.md

@@ -21,6 +21,15 @@ Forecastle 1.x and Elixir 1.18 or later.
 
 ### Changed
 
+- `mix forecastle.relup` is now `mix castle.relup`, and the README documents it
+  as Castle's while naming Forecastle as its implementer. There is no
+  compatibility alias, so a build pipeline calling the old name has to be
+  updated. Nothing changes in `deps` — Castle already brings Forecastle in at
+  build time, and which half implements a task is a packaging decision rather
+  than something a consumer should have to learn. The appup compiler is **not**
+  renamed and is unaffected: it stays `mix compile.appup`, named by its
+  `:compilers` entry rather than by either package.
+  ([forecastle#24](https://github.com/ausimian/forecastle/issues/24))
 - Release-management commands now raise on refusal or a returned OTP error, so
   `bin/castle` exits non-zero. Successful command output is unchanged.
 - Operator-facing errors and warnings are shorter, distinguish preflight

design/upgrade-tooling.md

@@ -1,6 +1,9 @@
 # Upgrade tooling: appups, relups, and the tasks around them
 
-**Status:** accepted, unimplemented. Supersedes nothing.
+**Status:** accepted. D1 is implemented — the tasks are named `castle.*` as of
+[forecastle#24](https://github.com/ausimian/forecastle/issues/24), enforced by
+[castle#33](https://github.com/ausimian/castle/issues/33). The rest is
+unimplemented. Supersedes nothing.
 **Spans:** [ausimian/castle](https://github.com/ausimian/castle) and
 [ausimian/forecastle](https://github.com/ausimian/forecastle).
 **Tracked by:** [castle#32](https://github.com/ausimian/castle/issues/32).
@@ -55,7 +58,7 @@ appup lookups in `appup_file/2` — and those only exist **after** `:assemble`.
 So the real workflow is:
 
 1. `mix release` — assemble the target.
-2. `mix forecastle.relup --target … --fromto …` — write `relup` to the project root.
+2. `mix castle.relup --target … --fromto …` — write `relup` to the project root.
 3. `mix release --overwrite` — assemble it again, this time packaging the relup.
 
 The double build is mandatory and undocumented. Worse, it makes a mutable file in

lib/castle.ex

@@ -65,9 +65,18 @@ defmodule Castle do
 
   The project must also provide:
 
-    * An appup for each application being upgraded, configured with the
-      `:appup` project key and `compilers: Mix.compilers() ++ [:appup]`.
-    * A relup generated by `mix forecastle.relup` and left in the project root.
+    * An appup for each application the project owns that has to be upgraded in
+      place, configured with the `:appup` project key and
+      `compilers: Mix.compilers() ++ [:appup]`.
+
+      Exactly which transitions need one depends on the strategy the relup is
+      generated with, on which applications changed and on who owns them, and
+      each direction is classified separately. `mix castle.relup` documents
+      those rules and is the authority on them; this list deliberately does not
+      restate them, because a summary short enough to belong here is wrong in
+      some case and a correct one is that task's `@moduledoc` copied into a
+      repository that cannot see it change.
+    * A relup generated by `mix castle.relup` and left in the project root.
     * `include_executables_for: [:unix]`.
 
   A custom `rel/env.sh.eex` is optional. Forecastle appends Castle's setup to

mix.lock

@@ -4,7 +4,7 @@
   "earmark_parser": {:hex, :earmark_parser, "1.4.46", "67607a0532e810c6f630a515c548d0b24949643f168cc556303bee4cf96105c7", [:mix], [], "hexpm", "9c44636e8a1c68c62f526b2dcd85d941dbbcee7ab82cf64ba06ce28bef8e89f5"},
   "ex_doc": {:hex, :ex_doc, "0.40.3", "4a972ffe64bc07dc605af487e98fc19b72a4185f55ca031b94c0552d6071c1d9", [:mix], [{:earmark_parser, "~> 1.4.44", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_c, ">= 0.1.0", [hex: :makeup_c, repo: "hexpm", optional: true]}, {:makeup_elixir, "~> 0.14 or ~> 1.0", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1 or ~> 1.0", [hex: :makeup_erlang, repo: "hexpm", optional: false]}, {:makeup_html, ">= 0.1.0", [hex: :makeup_html, repo: "hexpm", optional: true]}], "hexpm", "2756e357742fecd9749b489b85d67c9ce99c465f2e75728d9e6dc8d704b973de"},
   "file_system": {:hex, :file_system, "1.1.1", "31864f4685b0148f25bd3fbef2b1228457c0c89024ad67f7a81a3ffbc0bbad3a", [:mix], [], "hexpm", "7a15ff97dfe526aeefb090a7a9d3d03aa907e100e262a0f8f7746b78f8f87a5d"},
-  "forecastle": {:git, "https://github.com/ausimian/forecastle.git", "e43f8808a4470a6952013cc8af56bec64877ef89", [branch: "feature/upgrade-tooling"]},
+  "forecastle": {:git, "https://github.com/ausimian/forecastle.git", "a77e97c9f14b07ca4e532ff98e626a6106548cba", [branch: "feature/upgrade-tooling"]},
   "jason": {:hex, :jason, "1.4.5", "2e3a008590b0b8d7388c20293e9dcc9cf3e5d642fd2a114e4cbbb52e595d940a", [:mix], [{:decimal, "~> 1.0 or ~> 2.0 or ~> 3.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "b0c823996102bcd0239b3c2444eb00409b72f6a140c1950bc8b457d836b30684"},
   "makeup": {:hex, :makeup, "1.2.2", "882d46dc0905e9ff7abf2aab61a7e6b3dcc555533977d8a23b06019e6c89ac94", [:mix], [{:nimble_parsec, "~> 1.4", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "9a1a24e5b343b8ae16abea0822c10a6f75da27af7fa802ada5251f7579bfccfa"},
   "makeup_elixir": {:hex, :makeup_elixir, "1.0.1", "e928a4f984e795e41e3abd27bfc09f51db16ab8ba1aebdba2b3a575437efafc2", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "7284900d412a3e5cfd97fdaed4f5ed389b8f2b4cb49efc0eb3bd10e2febf9507"},