chemenu/instructions/dev/version-parts.md

---
type: types/instruction.md
name: version-parts
description: Which part of the stack version a change bumps - the compatibility question (is the new version a drop-in replacement?) separated from the migration question (must existing content change?), plus what to do before a breaking bump.
---
# Pick the version part for a stack change

Two questions decide a version bump, and they are **not the same question**:

1. **Is the new version a drop-in replacement for the old one?** This is what the version
   number itself says. Compatibility is read off the **leftmost non-zero component** - on this
   stack (`4.x`) that is MAJOR, on a `0.x` stack it is MINOR. A bump that changes it is called
   *boundary-crossing* below, because that is the term `version bump` and `docs verify` use in
   their own messages.
2. **Must existing content be migrated?** This is a *consequence* a boundary crossing may or
   may not have. `kb/` staying untouched does not make a change compatible, and
   `version bump --no-migration` exists precisely because boundary-crossing bumps with an
   untouched corpus are a real case.

Getting these backwards is how a genuinely breaking change ships as a MINOR. It happened once
already (see the case study at the end), which is why this file exists.

<!-- wikitool:toc -->
## Contents

- [The candidate model](#the-candidate-model)
- [When to run](#when-to-run)
- [Steps](#steps)
- [Decision points](#decision-points)
- [Scope](#scope)
- [Case study: 2.0.0](#case-study-200)
<!-- /wikitool:toc -->

## The candidate model

Between two releases the stack carries **one running candidate**, not a fresh version per
`bump`. Before that, every bump minted a number *and* a release: CI's version gate requires
`VERSION` to move on every stack-touching push, and `release.yml` fires on every `VERSION`
move, so releases were being cut at commit granularity. 2026-09-03 produced four of them in
six hours (`4.3.0` through `4.3.3`) for one arc of work - all four real, none of them a
meaningful unit to anyone downstream. A candidate closes that gap without touching the gate:
`VERSION` still moves on every bump, it just escalates the *same* number instead of handing out
a new one, and only `version release` turns it into something the release workflow acts on.

- **State lives in `VERSION` itself**, as an optional `-beta.N` suffix (`4.4.0-beta.3`). No
  second state file: the last release is read back out of `CHANGES.md` (the newest entry with no
  suffix), and the escalation stage is the difference between the candidate's base and that
  release - derived, not stored.
- **`--major`/`--minor`/`--patch` is max-wins escalation**, not a step you can undo. A `--patch`
  bump on a candidate already at MINOR only advances its bump count (`N`); nothing ever steps a
  candidate back down. Declaring the part is still your judgment call, made the same way the
  steps below describe - `escalate()` only ever raises it further.
- **A candidate is never released.** Pre-release is a dev-checkout state; `release.yml` only acts
  on a suffix-free `VERSION`, so a distributed instance never sees a `-beta.` version at all, and
  its parser never has to know the suffix exists.
- **One `CHANGES.md` entry per candidate**, not per bump. The first bump of a candidate opens it
  (heading, date, author, and a machine-managed `<!-- wikitool:bumps -->` list seeded with that
  bump's `--title`, graded by `--impact`); every later bump of the *same* candidate updates that
  entry in place - heading, date and the bumps list all move, but the entry's own prose is left
  alone. `version notes` therefore still prints exactly one entry per release, whatever a
  candidate's history of bumps looked like.
- **The entry is layered, not one undifferentiated block.** A long-running candidate can collect
  dozens of bumps, chronological and equally weighted, which is unreadable as a release
  announcement - `5.0.0` did this at ~1440 lines for one entry. So the entry reads, top to bottom,
  as four layers with different authors and different lifetimes:

  1. **Heading, author, breaking/migration lines** - written by `version bump`, anchored right
     above the bump list so the line an operator most needs to act on never sits beneath a list
     that can run long.
  2. **The bump list**, grouped `**High/Medium/Low impact**` (empty groups omitted) - rendered by
     `version bump`'s `--impact` (default `medium`), corrected after the fact by `version regrade`.
     Flat and ungrouped, exactly as before this layering existed, when every bump is `medium` - the
     common case, and the shape every pre-existing region still is.
  3. **The release summary** - a short paragraph, written once, by hand, when the candidate is
     ready to ship. `version release` refuses to close an entry with two or more bumps and no
     summary here; a one-bump entry is exempt, since there the bump's own changeset already reads
     as the summary.
  4. **The changesets**, one `### <bump title>` heading per bump, in chronological order - the
     detail a reader follows into from the graded list above. A changeset is a few sentences,
     not the full rationale; what needs more than that belongs in the issue tracker, not here.

  The list is the index into the changesets, which is why the bump list's title text and a
  changeset's `###` heading are the same string.
- **`version bump` opens or continues a candidate; `version release` fixes one.** Only `release`
  strips the suffix and turns the entry into a real, closed release - see its own row in
  `tools/CONTRACT.md`. Nothing else does, and nothing auto-fixes a candidate on its own.

## When to run

Before every `tools/wikitool version bump` - the `stack-dev` skill's step 4 sends you here.
Read it in full the first time a change looks like it might be boundary-crossing; afterwards
the three-line test below is usually enough.

## Steps

1. **Apply the drop-in test.** The bump is boundary-crossing if **either** half fails:

   - **Forward:** an existing instance can install the new machinery by copying `tools/`,
     `types/`, `instructions/`, `AGENTS.md`, `VERSION` and `.wikitool-release.json` over itself,
     and everything that worked before still works - with **no** hand-work by the user and **no**
     migration script. Any step beyond the copy, however small, fails this half.
   - **Backward:** having installed the new version, the user can put the old one back and be
     where they started. A state file the old version cannot read, a rewritten corpus, a
     renamed stamp - anything that makes the downgrade fail or leave a broken instance - fails
     this half.

   Content migration is one way to fail the forward half, not the definition of it.

2. **Check the catalogue** when the answer still feels like a judgment call. Each of these
   crosses the boundary with `kb/` entirely untouched:

   | What changed | Why the swap is not drop-in |
   |---|---|
   | The update path - `update_url`, the release feed, the repo it points at | The instance cannot repair its own `.wikitool-release.json`: it is machine-written, and invariant 1 forbids the hand-edit. The channel that would have told it to update is the channel that broke |
   | The release artefact's name | Every download script and every pin against it breaks |
   | The Python package's import name | `from <old> import ...` outside the shipped tree breaks |
   | A command, subcommand, or flag that was removed or renamed | Scripts, CI workflows and instruction files calling the old spelling break |
   | An environment variable's name | An instance configured through it silently loses the configuration |
   | The shape of a machine-read file - `.wikitool-kb.json`, `.wikitool-release.json`, a generated index | The old version cannot read what the new one wrote, so the downgrade half fails even if the upgrade half passed |
   | A type-spec's required fields | Existing pages stop validating - this one crosses *and* needs a content migration |

   The catalogue is illustrative, not exhaustive. When something is not on it, go back to step 1.

3. **Otherwise pick the compatible part:**

   | Change | Part |
   |---|---|
   | Fix, no interface change | `--patch` |
   | New capability, drop-in in both directions | `--minor` |

4. **Stop and talk to the user before the bump that first escalates a candidate past the
   boundary.** It is expensive in a way the other two parts are not: every existing instance pays
   for it, once, by hand. That escalation happens exactly once per candidate - a later bump that
   keeps the candidate at the same stage (another `--major` on one already there, say) does not
   re-cross anything and needs no second conversation. Put in front of the user, in this order:

   - **What breaks**, concretely - which file, which name, which call site.
   - **What each existing instance must do**, as the steps they would actually run.
   - **The alternatives**, so the break is a choice and not a side effect:
     - *Avoid it* - keep the old name as an alias, read both file shapes, accept both flag
       spellings. A compatibility shim carried for one release is usually cheaper than a
       migration everyone runs.
     - *Defer and batch it* - hold the break until the next boundary crossing, so instances pay
       once instead of twice.
     - *Split it* - ship the compatible half now, the breaking half later behind a deprecation
       window that the changelog announces in advance.
   - **Your recommendation**, with the trade-off named.

   Then wait for an explicit go-ahead. Do not bump across the boundary on your own initiative.

5. **Grade the bump while you are making it, with `--impact high|medium|low`** (default
   `medium`) - the judgment is easiest right after you did the work, not weeks later staring at a
   chronological list. It is not final: `version regrade` corrects it before release if the
   candidate's overall shape changes the read on an earlier bump. Then record the break in the
   escalation bump itself. The bump that first crosses the boundary requires
   `--breaking "<what breaks>"`, which writes a `**Breaking Change:**` line into the entry:

   ```bash
   tools/wikitool version bump --major \
     --title "<what changed>" \
     --breaking "<what stops working, and what an instance must do about it>" \
     --no-migration "<why no page has to change>"     # only if that is true
   ```

   The line, once written, stays in the entry across every later bump of the same candidate -
   a follow-up `--major` does not need to repeat `--breaking`, because the entry it would repeat
   it into is the same one. `--breaking` is refused on a bump that crosses nothing, and required
   on the one that does. `docs verify` checks the newest boundary-crossing entry still carries
   the line. Write it for the operator of an instance that has not read this repository: what
   stops working, and what they do about it.

6. **Then answer the migration question separately.** Boundary-crossing and
   content-migrating are independent:

   - Content must change → write the migration document under `instructions/migrations/` per
     [migrate-corpus.md](../migrate-corpus.md). The escalation bump finds it by the document's
     `migrates_to:` field, matched against the candidate's **base** - a document targets the
     release the candidate will become, never a `-beta.N` form of it.
   - Content need not change → `--no-migration "<reason>"`, which records that in the entry.

   Both are also needed by `docs verify`, for the same reason: an instance that learns it must
   migrate, with nothing telling it how, is a dead end. Like `--breaking`, both persist across
   later bumps of the same candidate without being repeated.

   **A `--no-migration` answer can turn out wrong later in the same candidate**, and that is not
   a hand-edit: a bump escalates, a second change lands under the same running number, and now
   content does have to move after all. Write the migration document first, then retract the line
   with `version bump --migration-required` - it removes the `**Migration:** none required` line
   the earlier bump wrote, and refuses unless a document already targets the new base. Nothing
   else takes that statement back: the line is machine-written (invariant 1), `docs verify` is
   satisfied by its bare presence, and the escalation checks in this step run only on the bump
   that *first* crosses the boundary - so a candidate that keeps a stale `none required` line is
   never reported by anything. The 5.0.0 candidate is the case: it declared `--no-migration` for
   a TOC-verification change, then absorbed a schema removal that migrates 152 pages.

7. **Review the graded list before fixing the candidate, and regrade what reads wrong.** Run
   `tools/wikitool version regrade` with no arguments - it lists every bump at its current grade,
   numbered in rendered order. A candidate that grew over several sessions often has a bump graded
   in isolation that reads differently once the whole shape is visible; `version regrade 3 7
   --impact high` corrects one or several positions against a single read of that list, put the
   result in front of the user, and re-list to confirm. Only then run
   `tools/wikitool version release`, which strips the `-beta.N` suffix and closes the entry - see
   its row in `tools/CONTRACT.md`. That is also the point to pass a summarising `--title` if the
   candidate collected several bump titles along the way; without one, the heading simply keeps
   whichever bump last set it.

8. **Write the entry's prose - the summary, and each bump's own changeset.** `bump` leaves both
   empty on purpose. The **summary** is a short paragraph (a few sentences) written once, at
   release time, right below the graded bump list: what this release is about, and why, for a
   reader who will not read the changesets underneath. `version release` refuses to close an
   entry that collected two or more bumps and has no summary - a one-bump entry is exempt, since
   there the bump's changeset already reads as one. Each **changeset**, under its own
   `### <bump title>` heading, is a few sentences on what changed and why - it is the one thing a
   future reader cannot reconstruct from the diff, but it is not the place for the full rationale
   of a decision; that belongs in the issue tracker or the commit history, and a changeset that
   is growing past a paragraph or two is a sign it belongs there instead.

## Decision points

- **The change ships no code - only `README.md`, `INSTALL.md`, `EVALS.md`, or `.gitea/`?** No
  bump at all; CI's version gate is scoped to what changes behaviour.
- **A break you can see coming but are not making yet?** File it as an issue and let it
  accumulate. Boundary crossings are cheaper in batches, and step 4's "defer" alternative is
  only real if someone wrote the break down.
- **Unsure between MINOR and boundary-crossing?** It is boundary-crossing. The cost of an
  unnecessary MAJOR is one extra release note; the cost of a MINOR that actually breaks is an
  instance whose update path fails while its version number promised it would not.
- **The break only affects this repository, not a distributed instance** - something under
  `instructions/dev/`, say? Then it is not a stack break at all: `dist export` never shipped it.
  Judge by what an *exported* instance sees.

## Scope

Applies to the stack version in `VERSION` - `tools/`, `types/`, `instructions/`, `AGENTS.md`
and the contracts. It says nothing about the content shape in `.wikitool-kb.json`, which is
advanced by `wikitool migrate done` and described by [migrate-corpus.md](../migrate-corpus.md),
and nothing about wiki content operations, which are logged in `kb/log.md` and carry no version
at all.

Choosing the part remains a judgment call, deliberately: `docs verify` checks that a
boundary-crossing entry *documents* its break and its migration, never that the part was chosen
correctly. No validator can tell a renamed flag from a new one.

## Case study: 2.0.0

The Chemenu rebranding renamed the repo, the release artefact and the Python package. No page
in `kb/` changed, so the first attempt was `1.9.0` - the migration question, answered correctly,
substituted for the compatibility question, which was never asked. Three things broke: every
existing instance's `update_url` pointed at a repo path that no longer existed and could not be
hand-repaired; the artefact name changed; the import name changed. The correct bump was
`--major --no-migration`, and the `CHANGES.md` entry for `2.0.0` carries the reasoning in full
under "Warum das trotzdem MAJOR ist". The error was caught by the user, not by the
documentation - which is what step 4 is for.