Skip to content

Commit 131ef59

Browse files
ausimianclaude
andcommitted
docs: stop offering an unsupported directory, and split the silence claim
Two claims a review found, both asserting more than the code does. The unpack doc offered RELDIR and the sasl releases_dir parameter as ways to name another release directory. rel_dir/0 is Path.join(Deployment.root_dir(), "releases") and consults neither, so setting one does not merely go unread: it moves the directory the handler unpacks into and keeps its records in, while the ERTS guard reading the target .rel (commands.ex:128) and the step writing the target configuration (commands.ex:743) both still resolve <root>/releases/<vsn>. The doc was directing operators into an upgrade that cannot complete. It now says so. AGENTS.md already had this right and cites issue #23; the omission was only in the public doc. The moduledoc said the commands that are questions "succeed with nothing to say at all". releases/0 is a question and prints a line per release through report!/1, which its own @doc promises, so automation was given the wrong stdout contract. What gets printed varies by command, not by kind: upgradable/0 and running/1 return {:ok, []}, releases/0 returns the table. Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 3e8a07d commit 131ef59

1 file changed

Lines changed: 13 additions & 6 deletions

File tree

lib/castle.ex

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,10 @@ defmodule Castle do
3333
3434
* A command that succeeds prints what it has to report, and returns `:ok`.
3535
The report is the output rather than the return value: there is nothing in
36-
`:ok` to inspect, and the commands that are questions succeed with
37-
nothing to say at all.
36+
`:ok` to inspect. What there is to print varies by command and not by
37+
kind - `upgradable/0` and `running/1` are questions that answer by not
38+
raising and print nothing at all, while `releases/0` is a question whose
39+
answer *is* its output, a line for every release the system knows about.
3840
3941
* A command that fails raises, and what it raises is not always
4042
`Castle.Error`. A refusal the command made itself, and an error
@@ -337,10 +339,15 @@ defmodule Castle do
337339
`bin/castle unpack <vsn>`, which builds the argument as
338340
`<release name>-<vsn>` - `name` is the tarball's name without its `.tar.gz`
339341
suffix, the way `:release_handler.unpack_release/1` takes it, and not a bare
340-
version. The tarball itself has to have been copied into the release directory
341-
`:release_handler` reads first — `releases/` under the deployment root, unless
342-
`RELDIR` or the `sasl` `releases_dir` parameter names another one, in which
343-
case the handler looks there and only there. It is the `<name>-<vsn>.tar.gz`
342+
version. The tarball itself has to have been copied into `releases/` under the
343+
deployment root, and that is the only release directory Castle resolves: it
344+
joins the name onto `code:root_dir()` and consults neither `RELDIR` nor the
345+
`sasl` `releases_dir` parameter. Setting either is not supported, and does not
346+
merely go unread - it moves the directory `:release_handler` unpacks into and
347+
keeps its records in, while the guard that reads the target's `.rel` and the
348+
step that writes the target's configuration both still resolve
349+
`<root>/releases/<vsn>`. The two stop agreeing on where a version lives, so
350+
such a deployment cannot complete an upgrade. It is the `<name>-<vsn>.tar.gz`
344351
that `mix release`'s `:tar` step packs, which is why `customize/1` defaults
345352
`:steps` to include it.
346353

0 commit comments

Comments
 (0)