torbenandClaude Code
45ae04cfee
The guide said a required migration is simply carried out, which contradicts upgrade-instance.md: the agent can stop after the first publish, leaving a valid intermediate state that migrate status resumes and doctor warns about. The guide now says so without retelling the instruction's steps. Files changed: - docs/how-to/update-an-instance.md Co-Authored-By: Claude Code <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
155 lines
8.6 KiB
Markdown
155 lines
8.6 KiB
Markdown
# Update an instance
|
|
|
|
Bring an instance installed from a release up to a newer release of the stack: the tools, types,
|
|
instructions and contracts. Your pages stay yours. The agent carries out the upgrade by following
|
|
[instructions/upgrade-instance.md](../../instructions/upgrade-instance.md), which sets the order of
|
|
the steps, what each one decides, and where the session has to restart. This page covers the
|
|
decision before it, and what you'll see along the way.
|
|
|
|
<!-- wikitool:toc -->
|
|
## Contents
|
|
|
|
- [What is running, and is there something newer?](#what-is-running-and-is-there-something-newer)
|
|
- [Read the notes first](#read-the-notes-first)
|
|
- [What you say](#what-you-say)
|
|
- [Where the agent stops](#where-the-agent-stops)
|
|
- [Where the release comes from, and whom you trust](#where-the-release-comes-from-and-whom-you-trust)
|
|
- [Two first-time cases](#two-first-time-cases)
|
|
- [Pitfalls](#pitfalls)
|
|
<!-- /wikitool:toc -->
|
|
|
|
## What is running, and is there something newer?
|
|
|
|
Every instance carries the version of the **stack**, not of its content. It is in `VERSION`, and
|
|
`.wikitool-release.json` beside it records where the release came from and when it was exported.
|
|
|
|
```bash
|
|
tools/wikitool version # what runs here, and where it came from
|
|
tools/wikitool version check # is there a newer release?
|
|
tools/wikitool version notes # what the newest release changes
|
|
```
|
|
|
|
`version check`, `version notes` and `dist upgrade --latest` are the only commands that go to the
|
|
network. All three ask the same release feed: the one named in the stamp, unless
|
|
`WIKITOOL_UPDATE_URL` overrides it. A feed that cannot be reached is reported as an error, **never**
|
|
as "up to date" and never as "no notes".
|
|
|
|
## Read the notes first
|
|
|
|
What a version number promises: two versions are compatible when they agree in the *leftmost
|
|
non-zero part*. `0.1.3 → 0.1.4` is a safe update and `0.1.3 → 0.2.0` is not. From `1.0.0` on, the
|
|
same rule reads as the familiar "a MAJOR breaks". `version check` says which case you are in
|
|
(`state: update` or `state: migration`).
|
|
|
|
That number only answers whether the new machinery can simply be copied over the old. Whether your
|
|
*content* has to be migrated is a second, independent question. So the release notes of a MAJOR
|
|
carry two separate lines, and both are worth reading before you start:
|
|
|
|
- **Breaking Change:** what stops working, and what this instance has to do about it.
|
|
- **Migration:** whether and how the pages are rewritten (`none required` when they are not).
|
|
|
|
`version notes` prints both. On an instance it reads them from the release feed, because an
|
|
instance's own `CHANGES.md` is a stub that an update never overwrites. It always asks for the
|
|
**newest** release, so while `VERSION` still names the old one, it answers with a version other than
|
|
the one installed, and says so on stderr. If the feed cannot be reached, the error names the release
|
|
page recorded as `release_url` in `.wikitool-release.json`. `--offline` sends you there directly.
|
|
|
|
Why the two questions are kept apart: [version-model.md](../explanation/version-model.md).
|
|
|
|
## What you say
|
|
|
|
```text
|
|
Update this instance to the latest release
|
|
```
|
|
|
|
## Where the agent stops
|
|
|
|
In the order you'll meet them:
|
|
|
|
- **The release notes.** The agent shows you both lines before it touches anything. A migration the
|
|
instance already owes from an earlier release is finished first.
|
|
- **A stack file you changed by hand.** `dist upgrade` lists every file that differs from what the
|
|
installed release shipped, instead of overwriting it silently. For each one, you decide: take the
|
|
release's version, or keep yours. Keeping yours means the file is reported again at every future
|
|
upgrade.
|
|
- **The preflight.** A new release may need other tools than the old one. If something is missing,
|
|
the preflight stops with exit 42 and says what to install, exactly as during installation.
|
|
- **The first publish.** The swapped machinery is published on its own, before any content changes.
|
|
That is far more than ten files, so the Mass-Update Gate (exit 42) shows you the list and the
|
|
`--confirm` line.
|
|
- **The session restart.** The running session still holds the *old* `AGENTS.md`, contracts and
|
|
skills, so the agent asks you to restart it before migrating content. The new session picks up
|
|
where the old one stopped.
|
|
- **A required migration.** The agent carries it out, and may come back to you with a question
|
|
while doing so: a migration document can reach a point that is yours to decide, such as a page
|
|
that contradicts another.
|
|
- **An offered migration.** It changes a file the instance owns, so taking it or declining it is
|
|
your decision.
|
|
- **The second publish,** of the migrated content, behind the same gate.
|
|
|
|
**A required migration can also be interrupted.** If the agent cannot complete one now, it stops
|
|
after the first publish and leaves it. That is a valid state: new machinery, content still in its
|
|
old form. `doctor` keeps warning until the migration is done, and a later session resumes with
|
|
`tools/wikitool migrate status`. The agent never records a migration it did not carry out, because
|
|
the content's version would then describe a shape the pages are not in.
|
|
|
|
If a step fails for a reason that isn't obvious, the agent stops and offers you a bug report rather
|
|
than improvising ([Troubleshoot](troubleshoot.md)).
|
|
|
|
`doctor` warns as long as the content's version (`kb_version` in `.wikitool-kb.json`) is behind
|
|
`VERSION` and migrations are still open. An instance older than `.wikitool-kb.json` has no such file
|
|
at all. In that case `tools/wikitool migrate baseline <version>` is called once, and nothing is
|
|
guessed.
|
|
|
|
## Where the release comes from, and whom you trust
|
|
|
|
`tools/wikitool dist upgrade --latest --expect <version>` asks the release feed for its newest
|
|
release, downloads the tarball and its `.sha256` into a scratch directory, checks one against the
|
|
other and applies the release. The scratch directory is removed on every exit, including
|
|
`--dry-run`. `--expect` is the version `version notes` showed you: the feed only knows its *newest*
|
|
release, and `--expect` refuses **before** downloading if a newer one has appeared since, rather
|
|
than applying something nobody read. Pre-releases (`-beta.N`) need `--pre`.
|
|
|
|
**What the checksum does, and what it does not do.** The `.sha256` comes from the same feed as the
|
|
tarball. It protects against a damaged transfer, not against a compromised feed. Whether a release
|
|
is genuine rests on your trust in the host whose feed the instance asks (`update_url` in the stamp).
|
|
Nothing forces https. A configured `http://` feed is a deliberate choice. `WIKITOOL_UPDATE_TOKEN`
|
|
is sent only to downloads on the same host as the feed.
|
|
|
|
**Offline, or with a tarball from someone else:** put the tarball and its `.sha256` side by side,
|
|
and the agent passes the file instead of `--latest` (`dist upgrade <tarball>`). A tarball has to
|
|
unpack to exactly one top-level directory, which is the shape the release workflow builds.
|
|
|
|
## Two first-time cases
|
|
|
|
**The first jump to a release that knows `--latest`:** the option does not exist in the instance
|
|
yet, because the instruction there belongs to the release being left. Fetch the tarball and the
|
|
`.sha256` once from the release page, put them side by side, and run `dist upgrade <tarball>`. From
|
|
the next release on, the instance has `--latest` itself.
|
|
|
|
**The first jump to `4.5.0` or later:** `dist upgrade` itself does not exist in the instance yet,
|
|
because it arrived with `4.5.0`. Use the tool from the unpacked *new* tarball and point it at the old
|
|
instance:
|
|
|
|
```bash
|
|
tar -xzf chemenu-stack-<version>.tar.gz
|
|
CHEMENU_ROOT="$PWD" chemenu-stack-<version>/tools/wikitool \
|
|
dist upgrade chemenu-stack-<version>.tar.gz --dry-run
|
|
```
|
|
|
|
`CHEMENU_ROOT` tells the package which corpus to work on ([configuration](../reference/configuration.md)).
|
|
Without it, the package would take the unpacked tarball itself for the instance. From the second
|
|
upgrade on, the instance carries the command and the instruction itself.
|
|
|
|
## Pitfalls
|
|
|
|
- An instance without a local `.wikitool-release.json`, or with one that has no `files` block (from
|
|
before `4.5.0`), gives `dist upgrade` nothing to detect a local change against, so it refuses
|
|
the swap. There is no repair for that today.
|
|
- Given a tarball or directory, `dist upgrade` downloads nothing. Only `--latest` downloads.
|
|
- To follow the swap by hand anyway, perhaps with a tool `wikitool` cannot run, use the file list in
|
|
the `files` block of `.wikitool-release.json`. The exceptions - `kb/CONVENTIONS.md`, every
|
|
`kb/*/COLLECTION.md`, `.wikitool-kb.json` - are in the
|
|
[`dist upgrade` record](../reference/commands/distribution-and-versioning.md#dist-upgrade), along
|
|
with what the command classifies and refuses.
|