torbenandClaude Opus 5.5
53383e7e9b
Files changed: - CHANGES.md - README.md - VERSION - docs/reference/README.md - docs/reference/commands/README.md - docs/reference/commands/catalog-and-log.md - docs/reference/commands/content-migrations.md - docs/reference/commands/distribution-and-versioning.md - docs/reference/commands/finding-and-checking.md - docs/reference/commands/git.md - docs/reference/commands/guideline-export.md - docs/reference/commands/instance-health.md - docs/reference/commands/links-and-citations.md - docs/reference/commands/pages.md - docs/reference/commands/provenance.md - docs/reference/commands/raw-material-and-uploads.md - docs/reference/commands/telemetry.md - docs/reference/commands/types-instructions-and-docs.md - docs/reference/commands/workshop-runs-and-session-budget.md - docs/reference/exit-codes.md - instructions/dev/doc-pull-through.md - tools/CONTRACT.md - tools/README.md - tools/chemenu/cli.py - tools/chemenu/cli_contract.py - tools/chemenu/commands/docs_verify.py - tools/chemenu/reference_doc.py - tools/chemenu/tests/test_reference_doc.py - tools/chemenu/toc.py Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
268 lines
7.5 KiB
Markdown
268 lines
7.5 KiB
Markdown
# Content migrations
|
|
|
|
The migrations a release may require of an instance's content, and recording that they ran.
|
|
|
|
<!-- wikitool:toc -->
|
|
## Contents
|
|
|
|
- [`migrate list`](#migrate-list)
|
|
- [`migrate status`](#migrate-status)
|
|
- [`migrate verify`](#migrate-verify)
|
|
- [`migrate done`](#migrate-done)
|
|
- [`migrate baseline`](#migrate-baseline)
|
|
<!-- /wikitool:toc -->
|
|
|
|
<!-- wikitool:reference-commands -->
|
|
## `migrate list`
|
|
|
|
List every migration document under `instructions/migrations/`.
|
|
|
|
**Synopsis**
|
|
|
|
- `wikitool migrate list [--json]`
|
|
|
|
**Options**
|
|
|
|
```text
|
|
--json Print the migrations as JSON
|
|
-h, --help Show this message and exit.
|
|
```
|
|
|
|
**Examples**
|
|
|
|
```bash
|
|
tools/wikitool migrate list
|
|
```
|
|
|
|
**Behaviour**
|
|
|
|
- Lists every migration document under `instructions/migrations/`, oldest target first, with its kind and obligation.
|
|
- Never fails. Read-only and **exempt from the Iteration Budget Gate**.
|
|
|
|
**Properties**
|
|
|
|
- Changes files: no
|
|
- Idempotent: yes
|
|
- Atomic: Read-only
|
|
- Counts toward the session call budget: no
|
|
- Can reach the network: no
|
|
|
|
**Exit codes**
|
|
|
|
- `0` - success
|
|
|
|
**See also**
|
|
|
|
- `wikitool migrate status` - which of them this instance still owes
|
|
- `instructions/migrate-corpus.md` - how a migration is run
|
|
|
|
## `migrate status`
|
|
|
|
Show the migrations this instance still owes, in the order they must run.
|
|
|
|
**Synopsis**
|
|
|
|
- `wikitool migrate status [--json]`
|
|
|
|
**Options**
|
|
|
|
```text
|
|
--json Print the chain as JSON
|
|
-h, --help Show this message and exit.
|
|
```
|
|
|
|
**Examples**
|
|
|
|
```bash
|
|
tools/wikitool migrate status
|
|
tools/wikitool migrate status --json
|
|
```
|
|
|
|
**Behaviour**
|
|
|
|
- Shows every **required** migration whose `migrates_to` lies in `(kb_version, VERSION]`, in the order it must run.
|
|
- `offered` migrations are listed separately above the chain: they never block, never count as owed, and are bounded by the applied ledger rather than by `kb_version` - taking one does not move the version.
|
|
- With a release stamp present, also reports which shipped files this instance has since edited (from the per-file sha256 in `.wikitool-release.json`) - which says whether an offer may be copied over or has to be reconciled by hand. Without a stamp that question is reported as unanswerable rather than answered.
|
|
- Exits 1 only when the content version is undeclared (`.wikitool-kb.json` missing) or `VERSION` is unreadable; it never guesses the content's shape.
|
|
- Read-only, safe to retry freely, and exempt from the Iteration Budget Gate.
|
|
|
|
**Properties**
|
|
|
|
- Changes files: no
|
|
- Idempotent: yes
|
|
- Atomic: Read-only
|
|
- Counts toward the session call budget: no
|
|
- Can reach the network: no
|
|
|
|
**Exit codes**
|
|
|
|
- `0` - success
|
|
- `1` - `.wikitool-kb.json` is missing - the content version is undeclared
|
|
- `1` - `VERSION` is unreadable
|
|
|
|
**See also**
|
|
|
|
- `wikitool migrate done` - records one as applied
|
|
- `instructions/migrate-corpus.md` - how a migration is run
|
|
- `instructions/upgrade-instance.md` - where an upgrade checks this
|
|
|
|
## `migrate verify`
|
|
|
|
Compare `kb/` against a git revision on the invariants a content migration must not change.
|
|
|
|
**Synopsis**
|
|
|
|
- `wikitool migrate verify --from <rev> [--path P ...] [--expect-body-change] [--json] [--fail-on-error]`
|
|
|
|
**Options**
|
|
|
|
```text
|
|
--from <str> Git revision to compare against, e.g. HEAD [required]
|
|
--path <str> Limit to a subtree, repeatable (e.g. kb/concepts)
|
|
--expect-body-change Also report pages whose body did not change at all
|
|
--json Print the diff as JSON
|
|
--fail-on-error Exit 1 if any invariant changed
|
|
-h, --help Show this message and exit.
|
|
```
|
|
|
|
**Examples**
|
|
|
|
```bash
|
|
tools/wikitool migrate verify --from HEAD
|
|
tools/wikitool migrate verify --from HEAD --path kb/concepts --expect-body-change
|
|
```
|
|
|
|
**Behaviour**
|
|
|
|
- Compares `kb/` against the revision `--from` on the invariants a content migration must not change: wikilink and citation **counts** (not sets), footnote definitions, H1, structural frontmatter, and the **count of generated-region marker pairs**.
|
|
- Pages are matched by **title**, not path, so a page `move` (or `move --reconcile`) relocated compares as itself - reported separately as `moved` - rather than as a removed-and-added pair.
|
|
- Reports added and removed pages without failing on them.
|
|
- `--expect-body-change` additionally flags a page whose body did not change at all.
|
|
- Not migration-specific: worth running after any bulk rewrite.
|
|
- Exits 0 whatever it finds unless `--fail-on-error` is passed.
|
|
- Read-only and exempt from the Iteration Budget Gate.
|
|
|
|
**Properties**
|
|
|
|
- Changes files: no
|
|
- Idempotent: yes
|
|
- Atomic: Read-only
|
|
- Counts toward the session call budget: no
|
|
- Can reach the network: no
|
|
|
|
**Exit codes**
|
|
|
|
- `0` - success
|
|
- `1` - Only with `--fail-on-error`: an invariant changed
|
|
- `1` - `--from` is not a revision in this repository
|
|
|
|
**See also**
|
|
|
|
- `instructions/migrate-corpus.md` - where a migration runs this
|
|
- `wikitool lint` - the single-revision checks
|
|
|
|
## `migrate done`
|
|
|
|
Record one migration as applied, advancing `kb_version` in `.wikitool-kb.json`.
|
|
|
|
**Synopsis**
|
|
|
|
- `wikitool migrate done <version> [--pages N] [--dry-run]`
|
|
|
|
**Options**
|
|
|
|
```text
|
|
Arguments:
|
|
version The migration's target version, e.g. 1.4.0 [required]
|
|
|
|
Options:
|
|
--pages <int> How many pages it touched
|
|
--dry-run Report without writing
|
|
-h, --help Show this message and exit.
|
|
```
|
|
|
|
**Examples**
|
|
|
|
```bash
|
|
tools/wikitool migrate done 7.0.0 --pages 42 --dry-run
|
|
tools/wikitool migrate done 7.0.0 --pages 42
|
|
```
|
|
|
|
**Behaviour**
|
|
|
|
- Records one migration as applied, advancing `kb_version` in `.wikitool-kb.json` to its target.
|
|
- **Refuses any required version that is not the next link in the chain.**
|
|
- An `offered` migration is recorded in the applied ledger *without* moving `kb_version` and with no ordering rule applied. Re-recording one already in the ledger is a no-op, not an error - idempotent and safe to repeat.
|
|
- Not idempotent for a required migration: it advances the chain.
|
|
- `--dry-run` reports without writing.
|
|
|
|
**Properties**
|
|
|
|
- Changes files: yes
|
|
- Idempotent: no
|
|
- Atomic: Yes - single file write
|
|
- Counts toward the session call budget: yes
|
|
- Can reach the network: no
|
|
|
|
**Exit codes**
|
|
|
|
- `0` - success
|
|
- `1` - Unknown version, no `.wikitool-kb.json`, or nothing outstanding
|
|
- `1` - A *required* version that is not the next link in the chain
|
|
|
|
**See also**
|
|
|
|
- `wikitool migrate status` - the order to apply them in
|
|
- `instructions/migrate-corpus.md` - the migration procedure
|
|
|
|
## `migrate baseline`
|
|
|
|
Declare `kb_version` once, for an instance predating `.wikitool-kb.json`.
|
|
|
|
**Synopsis**
|
|
|
|
- `wikitool migrate baseline <version> [--force]`
|
|
|
|
**Options**
|
|
|
|
```text
|
|
Arguments:
|
|
version The shape this instance's content is already in [required]
|
|
|
|
Options:
|
|
--force Overwrite an existing declaration (not a substitute for `done`)
|
|
-h, --help Show this message and exit.
|
|
```
|
|
|
|
**Examples**
|
|
|
|
```bash
|
|
tools/wikitool migrate baseline 6.2.0
|
|
```
|
|
|
|
**Behaviour**
|
|
|
|
- Declares `kb_version` once, for an instance predating `.wikitool-kb.json`.
|
|
- Refuses to overwrite an existing declaration without `--force`. Advancing the version after a migration is `migrate done`, which checks the chain; this command does not.
|
|
- Safe to re-run with the same version.
|
|
|
|
**Properties**
|
|
|
|
- Changes files: yes
|
|
- Idempotent: yes
|
|
- Atomic: Yes - single file write
|
|
- Counts toward the session call budget: yes
|
|
- Can reach the network: no
|
|
|
|
**Exit codes**
|
|
|
|
- `0` - success
|
|
- `1` - Unparseable version
|
|
- `1` - A declaration already exists and `--force` was not passed
|
|
|
|
**See also**
|
|
|
|
- `wikitool migrate done` - advances the version after a migration
|
|
- `wikitool migrate status` - what is owed from the declared version
|
|
<!-- /wikitool:reference-commands -->
|