Read this in another language: Français
A release is a tag. There is no version to bump in any file: release.yml
stamps the tag into the binary with -ldflags, and a binary built any other way
falls back to the module version the Go toolchain records in it. Nothing can
drift from the tag, because nothing else holds the number.
The commits decide, not taste. Subjects follow
Conventional Commits, enforced
by the commit-msg hook and by the Commits workflow, and commitizen derives
the increment from them:
cz bump --dry-run # e.g. "bump: version 0.1.0 → 0.2.0 / tag to create: v0.2.0"fix moves the patch, feat the minor, a ! before the colon marks a break.
Before 1.0 a break stays inside 0.x (major_version_zero in pyproject.toml),
which is the same rule the Versioning section below states in prose.
Two deliberate limits. The version lives only in git tags
(version_provider = "scm"): a file carrying it would be a second source able to
disagree with the tag. And the CHANGELOG is written, not generated
(update_changelog_on_bump = false): its own header says which two kinds of
change deserve a line whatever their size, and a generator emitting every subject
would bury both under refactors. So commitizen proposes the number, the preflight
checks that the tag matches it, and the prose stays yours.
-
Move the
Unreleasedentries in CHANGELOG.md under a new## [X.Y.Z]heading. The release workflow reads that section for the body of the GitHub Release, so an entry that is not there is an entry nobody downloading a binary will see.Then
mise run docs:coverage, in the same commit. That heading is where the install commands in README.md and docs/install.md get the version they tell a reader to download — pinned rather thanlatest, because a mutable reference cannot be checked against a hash and adopts a release the day it is published. Moving the heading without regenerating leaves both pages one release behind, andfeint docs --checkexits 2 until they are not: at the pre-commit hook, on the pull request, in the preflight below, and one last time inside the release workflow, which refuses to publish rather than repairing anything.And
mise run release:surface, which answers the question that heading is about: does the section name what this release started and stopped serving. It diffs the committedcoverage/*-coverage.jsonof the latest tag against this tree's, and exits 2 when an operation that changed hands is named neither there nor in tools/release/unnamed.json. It prints the missing operations ready to paste. Three transitions are required: newly served, no longer served, and a refusal withdrawn — the one nobody thinks to publish and the one a consumer builds around (#326). -
Merge to
mainthrough a pull request, and wait for CI to be green. The tag builds from that commit and a published release cannot be replayed. -
Run the preflight, which replays offline everything that must hold:
mise run release:check -- v0.1.0
It checks a clean tree on
main, that the tag is free locally and on the remote,mise run check,mise run drift:checkat 0 — a release published with untriaged upstream operations advertises a coverage figure that is not true —feint docs --checkat 0,mise run release:surfaceat 0, the CHANGELOG section, committedcoverage/andcontracts/, and that conformance is green on this exact commit. It reports every verdict rather than stopping at the first, and it prints the commands to run once everything passes.It deliberately does not run the conformance suites itself: they need
scw,octl,exoand Terraform installed, and a release cut from a machine missing one of them would silently skip the very proof this project rests on. It asks CI whether they passed instead. -
Tag and push:
git tag -a v0.1.0 -m "v0.1.0" git push origin v0.1.0 -
Empty
tools/release/unnamed.json, if it held anything. Its entries excused operations from being named in the release you have just cut, and the window they were written for closed when the tag was pushed. An exemption that excuses nothing is refused — a stale exemption is a gate that quietly stopped covering what it names — somise run release:surfacegoes red on the next push until they are retired. That is the triage it is asking for, and it is one line of deletion. The list is empty in the ordinary case, which makes this step a no-op most of the time.
Pushing the tag is what publishes. It cannot be undone quietly: a tag has to be deleted on both sides, and a release that reached the world has been downloaded.
.github/workflows/release.yml, on v*:
- builds
linuxanddarwinbinaries foramd64andarm64, with the tag stamped in, - generates SHA-256 checksums and a CycloneDX SBOM (Syft),
- records SLSA build provenance for the binaries and attests the SBOM,
- signs the checksums with keyless Cosign,
- creates the GitHub Release with every artefact attached, including
provenance.intoto.jsonl.
That last asset is attached on purpose and is not redundant with the attestation recorded through GitHub's API: it is the file OpenSSF Scorecard's Signed-Releases control looks for. That control scores the five most recent releases, so the maximum is only reached once five consecutive releases carry it.
One step the workflow deliberately does not take. A binary formula needs the URL
and the SHA-256 of each published asset, and those exist only once the release
is up — so either the workflow pushes them into stephrobert/homebrew-feint,
which needs a cross-repository token this repository does not hold, or somebody
copies them and a gate refuses a stale copy. This project already refused the
first shape twice in writing (the Marketplace mirror in
.github/workflows/workflow-security.yml, the generated pages in
internal/cli/docs_release.go: a gate that refuses is safe; a gate that repairs
the repository is a second way in), so it is the second:
mise run release:formula > Formula/feint.rb # in the tap's checkoutNothing there is typed. release:formula fetches the release's own
cosign-signed checksums.txt and derives the file from it, so the digests in
the tap are the release's rather than a transcription of them. Commit, push, and
mise run release:tapanswers 0. It exits 2 while the tap serves anything else, and
.github/workflows/tap.yml runs it daily so a tap left behind by a release is
named within a day rather than two versions later. It is not on the
pull-request path: only whoever can push to the tap can clear its red, and a
gate a contributor cannot clear is one everybody learns to skip.
Anyone can check that a binary really came from this repository's workflow, and from which commit:
gh release download v0.1.0 --repo stephrobert/feint --pattern 'feint-linux-amd64'
gh attestation verify feint-linux-amd64 --repo stephrobert/feint
cosign verify-blob --bundle checksums.txt.cosign.bundle \
--certificate-identity-regexp 'https://github.com/stephrobert/feint/.*' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
checksums.txt
sha256sum -c checksums.txt --ignore-missingThe surfaces below are the whole of it. Anything not on this list carries no promise at all, and saying so plainly is the point: an emulator that promised its whole behaviour would be promising a moving copy of three clouds.
| surface | signal | frozen as |
|---|---|---|
/_feint/health |
schema_version |
internal/cli/testdata/frozen/health.json |
/_feint/routes |
schema_version |
internal/cli/testdata/frozen/routes.json |
/_feint/conformance |
schema_version |
internal/cli/testdata/frozen/conformance.json |
/_feint/trace |
schema_version |
internal/cli/testdata/frozen/trace.json |
/_feint/faults |
schema_version |
internal/cli/testdata/frozen/faults.json |
/_feint/s3 |
independent schema_version |
internal/cli/testdata/frozen/s3.json |
| the CLI's verbs, flags and exit codes | cliSurfaceVersion |
internal/cli/testdata/frozen/cli.json |
the JSON receipt of feint run --json |
its schema_version (runReceiptSchemaVersion) |
internal/cli/testdata/frozen/run.json |
| the state and snapshot formats | the document's own version | internal/cli/snapshot.go |
Serving more of a provider's API is never breaking, however much it changes. That asymmetry is what makes this window affordable: the surface that can break is small and enumerated above, and everything a provider pack gains lands outside it.
One minor release. A field or a verb that is going away is deprecated in one
release and removed no earlier than the next, and both events are lines in
CHANGELOG.md — a deprecation that appears and disappears in the same release is
not one.
One release rather than a generous number, deliberately. This is a 0.x project with one maintainer, and this repository has already measured what an unkeepable condition costs: the Exoscale preview label waited on somebody else's tracker and stayed wrong for months. A promise of one minor version, kept, is worth more than a longer one that is broken.
Every payload above carries schema_version, and it moves when the shape moves —
additions included, because the number means the surface changed, not the
surface broke. cliSurfaceVersion does the same for the verbs, the flags and
the exit codes. A fixture regenerated without its constant moving fails CI.
A consumer that reads a version it does not know should stop rather than guess. The shapes are additive within a version, so an unknown higher version is safe to read for the fields you already know; an unknown lower one means the emulator is older than your pipeline expects and the fields you rely on may not be there yet.
Concretely, and this is the whole recipe:
version="$(curl -sf localhost:4599/_feint/conformance | jq -r '.schema_version')"
[ "$version" -ge 3 ] || { echo "feint is older than this pipeline expects"; exit 1; }Reading a field without checking is what breaks silently: probed went from a
boolean to a string, and a pipeline treating it as truthy counted every refusal
as a success. That path is what #170 measures; this section is what it measures
against.
mise run compat:check builds the previous release out of this repository's own
history, starts both binaries offline, seeds them identically, and runs a set of
expressions a consumer could legitimately have written. Each lands in exactly one
bucket: compatible, explicitly broken, or silently wrong. A single unaccepted
silently-wrong verdict refuses the tag, and tools/release/preflight.sh enforces
that.
Against 0.8 it found two, both of them the probed expression in its two natural
forms:
| the consumer wrote | 0.8 | 0.9 |
|---|---|---|
select(.probed == true) |
some operations | none |
select(.probed) |
some operations | all of them |
The second is the worse one: every operation now reads as probed, refusals included, which is the exact overstatement #156 existed to remove reappearing in somebody else's pipeline.
Neither is fixable retroactively, and that is worth stating plainly rather
than leaving as a green gate. schema_version arrived with #132, after 0.8
shipped. A consumer of 0.8 could not have checked a signal that did not exist, so
the recipe above protects from 0.9 onward and not before. The two findings are
recorded in tools/compat/accepted.json with that reason, and they still print on
every run — recorded, never hidden.
The gate is about what happens next: from here on, a shape change either moves the
surface's schema_version or refuses the release.
Semantic Versioning. Before 1.0, the minor version moves on anything a client can observe.
What counts as breaking here is narrower than it looks, and it is worth stating
because this project's whole surface is somebody else's API. Serving more of a
provider's API is never breaking, however much it changes: a client asking for
an operation that used to 404 and now works is a client that got what it always
wanted. What breaks is on this project's own side — the CLI's verbs and flags,
the exit codes, the shape of /_feint/*, the state and snapshot formats, and
any emulated behaviour a test could have relied on.
Most of that list is no longer prose (#132). The shapes of /_feint/health,
/_feint/routes, /_feint/conformance and /_feint/trace, the CLI's verbs and
flags, and the exit codes each have a committed fixture under
internal/cli/testdata/frozen/ — the field tree, never a value — and two tests
gate them on every pull request:
TestTheFrozenSurfacesStillMatchTheirFixture fails when a shape moves and the
fixture did not, and TestASurfaceChangeDemandsItsVersionBump fails when the
fixture moved and the declared version did not. The three object payloads serve
that version as schema_version, so a consumer can branch on it; the gate is
what keeps the field from lying.
Changing one of these surfaces on purpose is four steps, in one commit:
- change the code;
mise run frozen:update— it appends the new form to the fixture's history at the next version, and never rewrites an entry;- bump the matching constant:
internal/core/emulator/schema.gofor the/_feint/*payloads,cliSurfaceVersionininternal/cli/cli.gofor the CLI — the tests stay red until this step, which is the point; - write the CHANGELOG line the bump is the signal for. Whether it lands as a fix or a break is this section's ordinary question; the fixture only proves the surface moved, not which of the two it was.
What is deliberately not frozen: the prose of the help text around the verbs
and flags, the values behind every frozen key (counters, identifiers, lists
that grow when routes are mounted), and the trace fields only some exchanges
carry (unread, violations). A freeze that caught any of those would go red
on routine runs and be disarmed within the week.
The snapshot format is the one of those that says its own version. Since #133 a
snapshot is {"format": "feint-snapshot", "version": N, "resources": [...]}, and
Restore refuses anything it cannot account for: another version, another
format, an unknown field. Bumping snapshotVersion in
internal/core/store/store.go is therefore a breaking change under this
section — and a file written by an older feint fails loudly at the boundary
rather than restoring three quarters of itself in silence, which is what it did
before.
The one exception worth calling out: a response shape corrected to match the provider's document is a fix, not a break, even when a downstream test was asserting the wrong one. That is the point of the project, and a test that depended on the emulator being wrong was measuring the emulator rather than the cloud.