Skip to content

changelog: cut v0.1.0, and stop saying we do not cut releases - #561

Merged
ohohoreilly merged 2 commits into
masterfrom
ohohoreilly/release-v0.1.0-prep
Sep 17, 2026
Merged

ohohoreilly merged 2 commits into
masterfrom
ohohoreilly/release-v0.1.0-prep

Conversation

@ohohoreilly

Copy link
Copy Markdown
Member

Stacked on #560 (the fragment fold) — the base shows only this commit once that merges. Draft for review; it is the "is this actually a release" decision, not a mechanical change.

Why 0.1.0 and not 1.0.0

Not a judgement call so much as matching what the project already claims everywhere else:

artifact version
@orlyatomics/orly (npm) 0.1.0
orly-mcp (npm) 0.1.0
orly-repl (npm) 0.1.0
clients/go module tag clients/go/v0.1.0

Tagging the repo v1.0.0 while every client it ships says 0.1.0 would be the odd choice. And 1.0.0 asserts a stability commitment that two gated RFCs — #218 (user-definable merges) and #255 (heterogeneous batched writes) — could still change out from under, along with the on-disk format.

What this actually buys

Worth being concrete, since the changelog has said "does not currently cut numbered releases" happily for months:

  • An immutable image. :latest is a moving tag. Nobody can pin. A v* tag makes docker.yml push :v0.1.0-<arch> and stitch :v0.1.0.
  • A version string in the binaries. make version runs git describe --tags --match 'v[0-9]*'; with no matching tag it falls back to a bare commit hash, so orlyc --help reports something meaningless today.

The change

Three things:

  1. That header line, replaced with the process as it actually is — semver, with an explicit pre-1.0 caveat that the language, wire protocol and on-disk format can move between minor versions.
  2. The folded [Unreleased] block moved under ## [v0.1.0] — 2026-09-17, with a short note that everything in it had already shipped.
  3. An empty [Unreleased] left above it.

No entry text is edited.

One thing that would have broken quietly

The empty [Unreleased] keeps its ### Fixed subheading on purpose. fold_changelog.py anchors on the literal string "## [Unreleased]\n\n### Fixed\n" and sys.exits if it cannot find it — so an empty section written the tidy way would have broken the next fold, at the moment someone was trying to land unrelated work.

Verified rather than reasoned about: folded a probe fragment against this exact structure and confirmed it lands in [Unreleased], above the released section, then reverted it.

Suggested sequence from here

  1. changelog: fold the five accumulated fragments into [Unreleased] #560 merges (fold).
  2. This merges.
  3. Tag v0.1.0-rc1. Its only job is to exercise docker.yml's tag path, which has never executed — the :${ver}-${arch} push and the version-tag stitch are gated on refs/tags/v*, and this repo has no v* tags. The last time never-executed publish code ran here it was ci: fix the multi-arch manifest check, which failed a correct manifest #559, where a gate failed a correct manifest.
  4. If the rc publishes clean, tag v0.1.0.

The rc is disposable; a bad v0.1.0 on a public repo is not.

Mechanical run of tools/fold_changelog.py. Five fragments, ten bullets: the
aarch64 portability pass and its CI job, the -msse2 removal, the multi-arch
docker workflow and its capacity reporting, the REPL :help and README rewrites,
the SemFiresOnlyAfterFlush deflake, and the aarch64 orlyc teardown hang.

They accumulated across the arm arc, which is exactly the case the fragment
directory exists for -- unique filenames cannot conflict, and nothing had to
touch CHANGELOG.md while five PRs were in flight.
The header line "The project does not currently cut numbered releases" was
accurate and is not any more. Replace it with what the process actually is:
semver with an explicit pre-1.0 caveat (the language, the wire protocol and the
on-disk format can still move between minor versions), fragments in
changelog.d/, folded into [Unreleased], moved under a version heading when a
release is cut.

Move the folded [Unreleased] block under `## [v0.1.0]` and leave an empty
[Unreleased] above it. Nothing in the entries changes -- everything in v0.1.0
had already shipped to master. What the tag buys is an immutable image and a
version string: today `:latest` is a moving tag and `make version` falls back to
a bare commit hash, because `git describe --match 'v[0-9]*'` has nothing to find.

0.1.0 rather than 1.0.0 because it is what the project already publishes
everywhere else -- @orlyatomics/orly, orly-mcp and orly-repl are all 0.1.0 on
npm, and the one tag in the repo is clients/go/v0.1.0 -- and because 1.0.0 would
claim a stability commitment that two gated RFCs (#218, #255) could still
change out from under.

The empty [Unreleased] keeps its `### Fixed` subheading deliberately:
fold_changelog.py anchors on the literal "## [Unreleased]\n\n### Fixed\n", so
dropping it would silently break the next fold. Checked by folding a probe
fragment against this structure and confirming it lands in [Unreleased] rather
than in the released section.
@ohohoreilly ohohoreilly self-assigned this Sep 17, 2026
@ohohoreilly
ohohoreilly merged commit 5375f5e into master Sep 17, 2026
10 checks passed
@ohohoreilly
ohohoreilly deleted the ohohoreilly/release-v0.1.0-prep branch September 17, 2026 10:13
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