Release and versioning map

This map shows how CKey's version numbers relate to one another, which build introduced each wire format and ABI, and how releases move between branches. VERSION is the source of truth for the current build, and CHANGELOG.md describes each build.

The four version numbers

Format numbers are shared across all profiles, so one profile's formats are not contiguous: Profile 2 went 0.9 → 0.15 → 0.18 → …

What the current build supports

Build 0.1.0-build.85, C ABI 4.

The encoders emit only the current formats. The image decoders read only the current layouts. Legacy formats are accepted only when the caller already has the codeword bytes.

Format history

Status is one of:

• current: emitted and decoded.
• legacy: no longer emitted, but codewords still decode.
• retired: neither emitted nor decoded. The specification is kept for the record.

The "Introduced" column is the build whose changelog entry first describes the format. Some format specifications were committed to spec/ a few builds later.

C ABI history

Between these, many functions were added without a bump (image decoding, calibration scores, text and extended profiles, Profile 0, the design system, print output).

Builds and commits

The repository history starts at dev.11. Builds without a row (dev.27, 29, 30, 33–36, 44) have no commit of their own: they were either never published or committed together with a neighbouring build. See the changelog.

Branches and the release flow

flowchart LR
  S["scratch<br/>maintainer only<br/>every build 0.1.0-build.N"] -->|promote reviewed builds| R["Stable-Release<br/>maintainer push, anyone may fork<br/>tagged releases"]
  R -->|fork or branch| C["community<br/>anyone<br/>unstable"]
  C -.->|maintainer picks changes| S

Community changes reach a release only through scratch. The maintainer brings them over, versions them as a new build, and promotes that build to Stable-Release.

Cutting a release

1. On scratch, pass CI and tools/check_version.py at the build being released, for example build.61.
2. Fast-forward or merge Stable-Release to that commit.
3. Tag the commit v0.1.0-build.61. Tags are immutable: never move, delete or reuse one.
4. Create a GitHub Release from the tag. Its title is the release name, for example CKey 0.1.0-build.61.
5. Add an entry to the top of CHANGELOG-STABLE.md with:
   • the tag;
   • the formats the release emits and the formats it reads;
   • the ABI version;
   • the builds it includes (dev.A to dev.B);
   • known limits.
6. Add a row to the release table below.

Deprecating a release

1. Retitle the GitHub Release Deprecated - {release name}, for example Deprecated - CKey 0.1.0-build.61.
2. Mark it deprecated in the release table and in CHANGELOG-STABLE.md. Name the release that replaces it and give the reason.
3. Keep the tag and its source. Deprecated means "do not use for new work", not deleted.

A format being superseded does not deprecate a release. Readers keep decoding legacy formats, as listed above.

Releases

Tag and version form

Decided at build 61: versions are 0.1.0-build.N, and tags are v0.1.0-build.N.

• Valid SemVer: build.N is a prerelease, so every package registry accepts it.
• Ordering: builds sort numerically (build.9 < build.10), and all of them sort before a final 0.1.0.
• Build count kept: it stays visible, as specification §8.1 asks.
• Old builds: builds 1–60 were named 0.1.0-dev.N. SemVer would sort build.61 before dev.60, because it compares the labels alphabetically. None of the dev builds was published or tagged, so no registry ever has to compare the two. The map keeps the old names for history.