Skip to content

Latest commit

 

History

History
314 lines (249 loc) · 15.3 KB

RELEASING.md

File metadata and controls

314 lines (249 loc) · 15.3 KB

Releasing

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.

Which 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.

Cutting one

  1. Move the Unreleased entries 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 than latest, 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, and feint docs --check exits 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 committed coverage/*-coverage.json of 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).

  2. Merge to main through a pull request, and wait for CI to be green. The tag builds from that commit and a published release cannot be replayed.

  3. 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:check at 0 — a release published with untriaged upstream operations advertises a coverage figure that is not true — feint docs --check at 0, mise run release:surface at 0, the CHANGELOG section, committed coverage/ and contracts/, 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, exo and 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.

  4. Tag and push:

    git tag -a v0.1.0 -m "v0.1.0"
    git push origin v0.1.0
  5. 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 — so mise run release:surface goes 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.

What the tag triggers

.github/workflows/release.yml, on v*:

  • builds linux and darwin binaries for amd64 and arm64, 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.

After the tag: the Homebrew tap

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 checkout

Nothing 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:tap

answers 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.

Verifying a release

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-missing

What you may depend on, and for how long

The 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.

The notice

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.

The signal

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.

The escape

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.

What the measurement found, and the one boundary it cannot protect

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.

Versioning

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.

Frozen surfaces

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:

  1. change the code;
  2. mise run frozen:update — it appends the new form to the fixture's history at the next version, and never rewrites an entry;
  3. bump the matching constant: internal/core/emulator/schema.go for the /_feint/* payloads, cliSurfaceVersion in internal/cli/cli.go for the CLI — the tests stay red until this step, which is the point;
  4. 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.