torben/chemenu
1
1 Fork 0
Code Issues 40 Pull Requests Actions Packages Releases 41 Wiki Activity
Files
main
chemenu/docs/reference/commands/content-migrations.md
T
torbenandClaude Opus 5.5 53383e7e9b
CI / verify (push) Successful in 6m11s
Details
CI / pwsh (push) Successful in 2m0s
Details
Release / release (push) Successful in 35s
Details
feat: docs reference generates a human command reference under docs/reference/ from the command records, one page per group plus exit codes and gates; toc never lands inside another generated region (#188) 
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
2026-10-06 21:29:01 +02:00

7.5 KiB
Raw Permalink Blame History

Content migrations

The migrations a release may require of an instance's content, and recording that they ran.

Contents

migrate list

List every migration document under instructions/migrations/.

Synopsis

  • wikitool migrate list [--json]

Options

  --json      Print the migrations as JSON
  -h, --help  Show this message and exit.

Examples

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

  --json      Print the chain as JSON
  -h, --help  Show this message and exit.

Examples

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

  --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

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

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

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

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

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
Reference in new issue View Git Blame Copy Permalink