docs: a SemVer compliance section, and what four tools do with a version #21

Merged

mikluko merged 1 commit from mikluko/octant/1724-semver-compliance into main

2026-09-06 20:08:54 +00:00

mikluko commented

2026-09-06 20:08:09 +00:00

(Migrated from github.com)

Octant: T1724, on map D1726. Docs only — no behaviour changes.

The README said what this action reads and nothing about how the versions it emits behave once they leave. Each of these is documented where its own tool lives and nowhere near the specification, so a reader holding a valid version had no way to meet one except by running into it.

The constraint the section is written under

No assumptions about what the reader does with a version. Not your deploy will fail, not your chart will not reconcile. Each entry states what a named tool does, under what input, and stops.

good   A constraint admits a pre-release only where the constraint's own
       literal carries one, so `*` matches no pre-release version.
bad    If you pin with `*` your pre-release charts will never deploy.

Read rather than recalled

Every claim was checked against a primary source in this session, and each entry names the version it was read against.

entry	how it was checked
`x/mod/semver`	`go doc` on v0.40.0 — the two deviations are declared in its own package doc, and `Canonical` documents discarding build metadata
`Masterminds/semver/v3`	measured on v3.5.0 across 9 constraints × 3 versions; the table in the README is that output
FluxCD selection	`getTagBySemver` fetched from `fluxcd/source-controller`, release v1.9.5
OCI tag grammar	`distribution-spec/spec.md`, plus `git check-ref-format` for the disagreement

Two things the checking sharpened beyond the ticket:

It is the -0 on the constraint literal that admits pre-releases, not the range's width. >=0.0.0 rejects 1.2.3-rc.1 and >=0.0.0-0 accepts it; ^1.0.0 rejects and ^1.0.0-0 accepts. The ticket had one example (1.2.x-0) and read it as a width question.
Flux uses Masterminds/semver/v3 itself. So its spec.ref.semver inherits the pre-release rule, and semver: "*" collects no pre-release tag at all — selection never gets a chance to rank one. The ticket had matching and selection as two separate facts; they chain.

Also stated

This project's own two departures, which nothing outside a test records: the uint64 bound on a component, and a git tag being read more loosely than a heading (leading v, and MAJOR/MAJOR.MINOR shorthand, so a moving v1 reads as a version).

gen-readme leaves the section alone — only the check table between the markers is generated. Suite green, vet and gofmt clean, and the document still reads valid=true.

Octant: [T1724](http://127.0.0.1:9876/T1724), on map [D1726](http://127.0.0.1:9876/D1726). Docs only — no behaviour changes. The README said what this action reads and nothing about how the versions it emits behave once they leave. Each of these is documented where its own tool lives and nowhere near the specification, so a reader holding a valid version had no way to meet one except by running into it. ## The constraint the section is written under **No assumptions about what the reader does with a version.** Not *your deploy will fail*, not *your chart will not reconcile*. Each entry states what a named tool does, under what input, and stops. ``` good A constraint admits a pre-release only where the constraint's own literal carries one, so `*` matches no pre-release version. bad If you pin with `*` your pre-release charts will never deploy. ``` ## Read rather than recalled Every claim was checked against a primary source in this session, and each entry names the version it was read against. | entry | how it was checked | |---|---| | `x/mod/semver` | `go doc` on v0.40.0 — the two deviations are declared in its own package doc, and `Canonical` documents discarding build metadata | | `Masterminds/semver/v3` | measured on v3.5.0 across 9 constraints × 3 versions; the table in the README is that output | | FluxCD selection | `getTagBySemver` fetched from `fluxcd/source-controller`, release v1.9.5 | | OCI tag grammar | `distribution-spec/spec.md`, plus `git check-ref-format` for the disagreement | Two things the checking sharpened beyond the ticket: - **It is the `-0` on the constraint literal that admits pre-releases, not the range's width.** `>=0.0.0` rejects `1.2.3-rc.1` and `>=0.0.0-0` accepts it; `^1.0.0` rejects and `^1.0.0-0` accepts. The ticket had one example (`1.2.x-0`) and read it as a width question. - **Flux uses `Masterminds/semver/v3` itself.** So its `spec.ref.semver` inherits the pre-release rule, and `semver: "*"` collects no pre-release tag *at all* — selection never gets a chance to rank one. The ticket had matching and selection as two separate facts; they chain. ## Also stated This project's own two departures, which nothing outside a test records: the `uint64` bound on a component, and a git tag being read more loosely than a heading (leading `v`, and `MAJOR`/`MAJOR.MINOR` shorthand, so a moving `v1` reads as a version). `gen-readme` leaves the section alone — only the check table between the markers is generated. Suite green, `vet` and `gofmt` clean, and the document still reads `valid=true`.