Skip to content

ci: enforce the minor-version parity instead of documenting it - #25

Merged
Tielem merged 2 commits into
devfrom
ci/enforce-version-parity
Sep 20, 2026
Merged

Tielem merged 2 commits into
devfrom
ci/enforce-version-parity

Conversation

@Tielem

@Tielem Tielem commented Sep 20, 2026

Copy link
Copy Markdown
Contributor

"0.19.x means implements spec 0.19" lived only in prose — CLAUDE.md and the changelog headers. That left it one typo from being silently false.

Three ways it drifted, none of which failed a build

Scenario Result
Spec → 0.20.0, repo implements it, heading dated ## [0.19.4] Claims 0.19, implements 0.20
Spec still 0.19, a bug fix dated ## [0.20.0] Claims a spec that does not exist
Pins bumped to 0.20.x packages, changelog left at 0.19.x Version and dependencies disagree

The check

Each implementation carries a SPEC_VERSION file naming the spec it implements, and scripts/check-version-parity.sh runs first in CI:

  1. the minor of the top CHANGELOG.md version equals the minor of SPEC_VERSION
  2. every Utos.* package pin is on that same minor — a package on a different minor is on a different spec line

Checked at PR time rather than release time, because at release time the mistake is a tag and a published artifact that cannot be taken back.

Verified by breaking it

Both halves, not just the happy path:

error: CHANGELOG.md names 0.20.0 but SPEC_VERSION says this repo implements 0.19.0.
       The minor is the contract: 0.20.x must mean implements spec 0.20.
       Either the version is wrong, or SPEC_VERSION was not updated when the spec moved.

error: Utos.Workflow is pinned at 0.20.1, but this repo implements spec 0.19.0.
       A package on a different minor is on a different spec line.

The message names which of the two is likely wrong, since "these disagree" is the easy half and "which one moved" is what a reader actually needs.

The script is runnable locally — scripts/check-version-parity.sh — so a version change can be checked before pushing.

"0.19.x means implements spec 0.19" lived only in prose, which left it one typo
from being silently false: a changelog heading naming 0.20.0 against a spec
still at 0.19, or an implementation of 0.20 released as 0.19.4, and nothing
anywhere would have failed.

This repo now carries a SPEC_VERSION file naming the spec it implements, and
check-version-parity.sh asserts two things in CI: the changelog's minor equals
it, and every Utos.* package pin is on that same minor. A package on a
different minor is on a different spec line, so a release claiming 0.19 while
depending on 0.20 packages is refused.

Checked at PR time rather than at release time, because at release time the
mistake is a tag and a published artifact that cannot be taken back.

Both halves verified by breaking them.
Windows git does not record the file mode, so chmod +x locally left it 100644
in the index and the CI step failed with 'Permission denied' before it could
check anything. Set with git update-index --chmod=+x, which is mode-only and
independent of the filesystem.
@Tielem
Tielem merged commit 9cf5516 into dev Sep 20, 2026
1 check passed
@Tielem
Tielem deleted the ci/enforce-version-parity branch September 20, 2026 15:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant