From f2de39f045fe3ac076f179ad028e39b8f576ad52 Mon Sep 17 00:00:00 2001 From: Arthur Date: Thu, 8 Oct 2026 21:08:43 +0200 Subject: [PATCH] docs: say that stack update ships in 0.4.0-rc.1 The admin guide and the operator notes named v0.3.0-beta.4 as the first release with `./stack update`. That release was never tagged: the update command shipped in v0.4.0-rc.1. The examples now move between the 0.4 release candidates, and the by-hand steps go from v0.3.0-beta.3 to v0.4.0-rc.1. --- docs/admin-guide.md | 20 ++++++++++---------- docs/agent/ops.md | 2 +- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/admin-guide.md b/docs/admin-guide.md index 5db54227..22e0394e 100644 --- a/docs/admin-guide.md +++ b/docs/admin-guide.md @@ -930,12 +930,12 @@ The famstack code is a git checkout, and a release is a tag. Updating means movi ./stack update ``` -That is the whole thing from v0.3.0-beta.4 onward. It fetches the releases, shows what the jump changes, moves the checkout, and sets your local edits aside and puts them back. +That is the whole thing from v0.4.0-rc.1 onward. It fetches the releases, shows what the jump changes, moves the checkout, and sets your local edits aside and puts them back. It does not restart anything. New code on disk is not new code running: a stacklet picks up a release when its containers are recreated, and when your family loses a service for thirty seconds is your call, not a side effect of updating. So the command works out which restarts the release actually earns and prints them: ``` - ✓ Updated to v0.3.0-beta.4 + ✓ Updated to v0.4.0-rc.2 Restart to pick it up ./stack restart docs @@ -944,7 +944,7 @@ It does not restart anything. New code on disk is not new code running: a stackl ```bash ./stack update --dry-run # show the plan, change nothing -./stack update v0.3.0-beta.4 # a specific release instead of the newest +./stack update v0.4.0-rc.2 # a specific release instead of the newest ./stack update --yes # skip the confirmation ``` @@ -953,30 +953,30 @@ would only be as fresh as your last fetch. It opens with the version and, once it knows, the move it is proposing: ``` - famstack 0.3.0-beta.3 + famstack 0.4.0-rc.1 Fetching releases... - Update v0.3.0-beta.3 → v0.3.0-beta.4 + Update v0.4.0-rc.1 → v0.4.0-rc.2 ``` A stacklet is named only if the release changed files inside it and it is running, so a documentation release asks for nothing. If the release changed anything under `lib/`, every running stacklet is named, because that is the code they all share. ### Updating by hand -`stack update` ships in v0.3.0-beta.4. Moving *to* that release, or moving between older ones, is the same steps typed out: +`stack update` ships in v0.4.0-rc.1. Moving *to* that release, or moving between older ones, is the same steps typed out: ```bash cd ~/famstack git fetch --tags git tag | tail -5 # what is available -git checkout v0.3.0-beta.4 # the one you want +git checkout v0.4.0-rc.1 # the one you want ./stack doctor ``` Then restart what the release touched. This prints the list: ```bash -git diff --name-only v0.3.0-beta.3 v0.3.0-beta.4 -- stacklets/ | cut -d/ -f2 | sort -u +git diff --name-only v0.3.0-beta.3 v0.4.0-rc.1 -- stacklets/ | cut -d/ -f2 | sort -u ``` Restart any of those you run. If the same command against `lib/` prints anything, the framework itself changed and everything wants a restart: @@ -994,8 +994,8 @@ Nothing in the update touches your instance. `stack.toml`, `users.toml`, `.stack If they collide, it winds the whole update back: you end up on the release you started from, with your edits exactly where they were and nothing left in the stash. Then it tells you how to go ahead deliberately: ``` - ⚠ Your edits collide with v0.3.0-beta.4. Nothing changed. - Back on v0.3.0-beta.3 with your edits where they were. + ⚠ Your edits collide with v0.4.0-rc.2. Nothing changed. + Back on v0.4.0-rc.1 with your edits where they were. The collision is in: • stacklets/docs/docker-compose.yml To take the release anyway, deal with that file first: diff --git a/docs/agent/ops.md b/docs/agent/ops.md index b7e53a74..ea0e23f9 100644 --- a/docs/agent/ops.md +++ b/docs/agent/ops.md @@ -129,7 +129,7 @@ A release is a git tag. `./stack update` moves the checkout to one and names wha - **It never restarts anything.** New code on disk is not new code running; recreating containers is the admin's decision. The command names what the release staled: stacklets it changed *and* that are running, or every running stacklet when anything under `lib/` changed. - **`./stack restart` with no argument applies it.** Every container is stamped at `stack up` with the commit it started from (`stack.commit`), so `stack list` and `stack doctor` report a stacklet running code the checkout has moved past, and a bare `restart` restarts those. A container with no stamp is reported as unknown, never guessed about. - **Local edits are set aside and put back.** If they collide with the release the whole update winds back: same release as before, edits in place, stash empty. Never leave a tree carrying conflict markers, a compose file with them in it does not parse. -- **Before v0.3.0-beta.4 there is no `update`.** By hand: `git fetch --tags && git checkout && ./stack doctor`, then restart what `git diff --name-only -- stacklets/` names. +- **Before v0.4.0-rc.1 there is no `update`.** By hand: `git fetch --tags && git checkout && ./stack doctor`, then restart what `git diff --name-only -- stacklets/` names. - **Works from a branch or a fork.** On `main` it moves to the tag and says the branch is left behind (`git switch main` returns). Tags are fetched from every remote, so a fork needs the project added as a remote or there is nothing to update to. - **A tag checkout is a detached HEAD.** `git pull` fails there. Never suggest `git pull origin main` as the fix: it succeeds and silently moves the instance onto unreleased code while `./stack version` still reports the last release. - **`./stack version` now says what is running,** not what the source constant claims: `0.3.0-beta.3-104-g9a5bdc9-dirty` is the tag, the distance past it, the commit, and an unclean tree. `version`, `status`, `list`, `doctor` and `update` all print the same string. `./stack doctor` adds a warning when a newer release exists, without fetching, so that half is as fresh as the last `git fetch`.