chemenu/docs/version-model.md

Why the stack version splits compatibility from migration

A stack version number looks like it answers one question. It actually answers two, and the two are independent of each other.

Two questions, not one

The first question is whether the new version is a drop-in replacement for the old one - whether an existing instance can install it, and can also go back, without anyone doing hand-work. That is what a version number is: a promise. The second question is whether the existing corpus in kb/ needs to change shape to keep working under the new version. These sound like the same question, because most of the time a change that breaks compatibility also happens to touch content, and most of the time a change that leaves content untouched also happens to be compatible. The correlation is real; it just is not a law. instructions/dev/version-parts.md carries the actual test for telling them apart and the steps that follow from it - this page is about why the split exists at all.

Why "kb/ untouched" is not proof of anything

The tempting shortcut is: if no page in kb/ had to change, the bump can't be that serious. This is exactly backwards for a class of changes that live entirely outside the corpus - a renamed release artefact, a Python import path, an environment variable, the URL an instance's own updater points at. None of those touch a single page. All of them can strand an existing instance just as thoroughly as a rewritten type-spec would. The corpus is the part of the stack that looks at itself; the compatibility question is about everything an instance depends on to keep functioning, most of which the corpus never sees.

Reading compatibility off the leftmost non-zero component

Semantic versioning gives every component a job, but only one of them is where an existing instance's tooling actually looks to decide "is this safe." On a 2.x stack that is MAJOR; on a still-pre-1.0 0.x stack, by the same convention, it's MINOR - the leftmost slot that isn't pinned to zero is the one an automated updater treats as the compatibility boundary. Bump anything to its left, or bump that slot itself, and the promise changes. Everything to the right of it can move as freely as the project likes without touching that promise. This is why the question "is it boundary-crossing" always resolves to one specific digit, not to a feeling about how big the change is.

Downgrade is half the promise

It's natural to test compatibility by only asking "does the upgrade work." The other half - "can an instance that upgraded put the old version back and land where it started" - carries equal weight, and it's the half that's easy to forget because forward motion is what everyone is testing for anyway. A state file the old version can no longer parse, a generated index in a new shape, a stamp file that got renamed: none of these have to break the upgrade to break the downgrade. An instance that can go forward but not back has already lost the property a compatible version number is supposed to guarantee.

A promise made to a machine, not only to a person

A human reading a changelog can absorb "this technically isn't compatible but it's fine, just update those two things by hand." An instance's own update mechanism cannot. It reads a version number, decides whether to pull the new release, and has no channel for nuance - which is exactly why the update path itself is one of the sharpest ways to cross the boundary invisibly: if the new version moves where updates come from, the very channel that would have told an instance to adjust is the channel that just broke. The version number isn't documentation aimed at a reader; it's an input consumed by code that has no other way to ask.

The 2.0.0 story

This isn't hypothetical for this stack. The rebranding that produced Chemenu renamed the repo, the release artefact, and the Python package - and left every page in kb/ untouched. The first instinct was a MINOR bump, on the reasoning that nothing in the corpus needed migrating. That reasoning was correct on its own terms and answered the wrong question. Three things broke underneath it: every existing instance's update_url pointed at a repo path that no longer existed and, because it's a machine-written file, couldn't be hand-repaired; the release artefact name changed, breaking every download script and pin against it; and the import name changed, breaking anything importing the package from outside the shipped tree. The corpus had nothing to say about any of this, because none of it lived in the corpus.

What caught the mistake was a person looking at the diff and asking whether it really was a drop-in replacement, not a validator. No check in docs verify or anywhere else confirms that a version part was chosen correctly - it only confirms that a boundary-crossing bump documents what it breaks. The 2.0.0 entry in CHANGES.md carries the corrected reasoning in full, and the version bump that shipped it was --major --no-migration: boundary-crossing and untouched corpus, at the same time, which is precisely the combination the two-question split exists to make visible.

Why a number is only spent by a release

Everything above is about what a version number promises. A separate question turned out to matter just as much in practice: how many numbers get handed out along the way to making one release. For a while the answer was "one per bump," and that turned out to be the wrong grain entirely.

The two things that actually consume a version number are a release and CI's version gate - and they disagree about granularity. The gate wants VERSION to move on every push that touches stack-shaped paths, which is a commit-level question: has this tree changed since the last push. A release wants to know something else: has this specific number been published, ever. Handing out a fresh number per bump answers the gate's question by accident and the release's question wrongly - it treats every bump as if it were about to ship, when most of them are steps toward a release that hasn't happened yet. Four bumps in one session, on the same day, for the same eventual release, produced four numbers that a version-check feed would have reported as four different available upgrades, three of which were never real.

The fix is not to slow the gate down - it still wants VERSION to move every time, and it still gets that. It's to stop treating every movement as a new number. Between two releases the stack now carries one running candidate, escalating through -beta.N as bumps accumulate, and only version release spends the number for real by fixing it and closing its changelog entry. A number is proposed by a bump and consumed by a release; conflating the two was the actual defect, not the arithmetic of any single bump.

This is also why a candidate never gets to a distributed instance. The promise a released version makes - "install this, and it is exactly what its number says" - has no equivalent for something still being decided during a single dev checkout's session. release.yml's only job with respect to this is refusing to act on a suffixed VERSION at all: not because a beta is unsafe, but because there is nothing yet to promise.

Where the procedure lives

The drop-in test, the catalogue of changes that cross the boundary with no page touched, and the steps for a boundary-crossing bump - the --breaking line, the migration document or --no-migration reason, talking to the user before bumping - are one procedure, kept at one place: instructions/dev/version-parts.md.