# Content migrations The migrations a release may require of an instance's content, and recording that they ran. ## Contents - [`migrate list`](#migrate-list) - [`migrate status`](#migrate-status) - [`migrate verify`](#migrate-verify) - [`migrate done`](#migrate-done) - [`migrate baseline`](#migrate-baseline) ## `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 [--path P ...] [--expect-body-change] [--json] [--fail-on-error]` **Options** ```text --from Git revision to compare against, e.g. HEAD [required] --path 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 [--pages N] [--dry-run]` **Options** ```text Arguments: version The migration's target version, e.g. 1.4.0 [required] Options: --pages 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 [--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