-dev to version

[danmt]

What's the itch?

The follow up commit to append a -dev to the version works but I was wondering if there was another alternative. What do modern teams use?

What would "done" feel like?

Clean release process

[dan-claude-bot]

Outcome: answer. Nothing needs minting from this. One alternative would
genuinely fit, it is not free, and it should not move before #112 lands — the
detail is at the bottom, and if you want it, say so and it gets its own thread
with a spec.

Verified this morning against main at
d4e133b and against
every release the family has actually run.

The follow-up commit is not a style choice — it falls out of three decisions already made

-dev is a state bit, not decoration. Four things read it:

• The interlock. lib/decide.sh rows 1–6
  decide "is this merge a release" by comparing the base tree's version to the
  head's. X.Y.Z-dev → X.Y.Z is the transition. Take the suffix away and
  there is nothing to transition from: row 5 (transition with no label) and
  row 4 (label with no transition) both stop being expressible, and "merging a
  release PR ships it" degrades to "merging a labeled PR ships it" — the exact
  single-signal design #1 constraint 8
  refused.
• changelog-armed keys on it —
  today,
  and still in the fragment mode actions/changelog-armed — fragment mode: the directory is the arming, and a bad entry fails on its own PR #115 specs (a -dev tree must hold fragments;
  a bare tree must have consumed them).
• drill-recorded keys on it: a dev tree has nothing to assert,
  a bare tree owes drills/X.Y.Z.md.
• Install honesty — the reason written into the commit message itself. main
  is installable (CAST_REF=main, rig's quick start), so a bare main means a
  dev install reports the released version.

And the structural fact underneath: the version lives in the tree, and the tag
goes on the ceremony PR's merge commit. The released tree and the re-armed
tree are therefore two different trees, so main takes two writes, necessarily.
Every alternative below drops one of those two premises. None of them is
"the same thing, without the commit".

What modern teams use

	shape	tools	follow-up commit?
A	dev suffix + post-release bump	Maven -SNAPSHOT + maven-release-plugin; the JVM default for ~20 years. We are here.	yes, by construction
B	version derived from git, no file in the tree	setuptools-scm, hatch-vcs, gradle axion/nebula, goreleaser, plain git describe	none — nothing to bump
C	version in the tree, bumped by the next release PR	release-please, changesets, semantic-release	none — main sits at the last release
D	bare version + build metadata	0.1.0+g1a2b3c stamped at build time	none

B — no. The tag becomes the source of truth, which means the tag door
becomes the only door and "a release is a PR, and merging it ships it"
(box#96, rig#47, cast#111 all converged on it) is reversed. It also fails
exactly where this family already got bitten: git-derived versions need tags and
depth, and incubator's images are built from Coolify's shallow, tag-less
checkouts — the same hole
incubator#45 is open
about. A rewrite of the doctrine to remove one bot commit.

C — the only one that fits, and it is the shape you bought yesterday.
changesets is #112 for prose; release-please is #112 for the version number.
main sits at the last released version and the next release PR carries the
bump, computed from the fragments' bump levels rather than typed. decide
already tolerates it —
row 3 is a
permanently-bare main, and it is already a green no-op. What it costs, precisely:

• Both other guards have to be re-keyed off the suffix and onto "is this the
  ceremony PR". Under a permanently-bare main, changelog-armed's fragment
  mode applies its bare-tree rules to every ordinary PR and refuses the
  fragment that PR just wrote (actions/changelog-armed — fragment mode: the directory is the arming, and a bad entry fails on its own PR #115, rule 4); drill-recorded demands
  drills/<last release>.md on every PR and passes by re-asserting the previous
  release's evidence. Both go from "this tree is not a release" to "could not
  tell" — and this repo's rule is that could-not-tell must never resolve to
  allowed.
• An install off main then reports the release it is not. Which is live
  right now as rig#118 —
  if the quick start installs the latest release rather than main, this cost
  mostly evaporates. That ruling is yours and it is upstream of this.

D — no. +g<sha> has to be appended by each repo's build: shell installer
(box, rig), npm (cast), two Dockerfiles (incubator). Four implementations of
what one line in a file does today, and it needs a build step where there is
currently none.

What our own history says about the cost

The hand-run version of this step was tried, and it is what the automation
replaced: box#98 and
cast#115 were bump PRs I opened
by hand on 2026-07-19. They took 15 minutes and 83 minutes to merge, and
main sat bare — impersonating the release — for exactly that long, each burning
a review round on a one-line arithmetic change.

Since then the automated bump has fired nine times with zero failures:
ceremony 0.1.1-dev, box 0.8.1/0.9.1, rig 0.1.1/0.2.1/0.3.1, cast
0.1.2/0.2.1, incubator 0.1.1. Every one a direct push; the
branch-protection fallback that opens a bump PR
(release.yml L292-L300)
has never fired anywhere. The mechanism you are asking about is the cheapest
version of this step this family has run.

Two honest weaknesses, since you asked

• The number is a placeholder, not a promise. version_next_dev always
  bumps the patch, so main advertises 0.2.1-dev while the next release may
  well be 0.3.0. Harmless — the ceremony PR types the real number and decide
  reads the transition either way — but main does carry a version that will
  often never exist. Every -SNAPSHOT shop lives with the same thing.
• It is the one write to main that nothing reviews. One file, arithmetic,
  and it fires no workflows on purpose (a GITHUB_TOKEN push is
  anti-recursive), but it is outside the PR flow. If that is the itch, the fix
  is not removing the bump — it is turning on branch protection so the fallback
  PR becomes the normal path, and the measured price of that is the 15–83 minute
  bare-main window above.

Recommendation

Keep it, and note it is about to get smaller. #117 (D6) deletes
## Unreleased and the changelog re-arm, so the post-release commit stops being
"version + changelog surgery" and becomes one file, one line — the part of it
that ever caused a real incident (box#108) is being removed by work already on
the board.

If you want C, the sequencing that makes sense is: #112 lands everywhere →
rig#118 rules → then one discussion for "the release PR computes the version
from the fragments", which is a real project (re-key two guards, teach the
assembler bump levels, doctrine) and worth doing deliberately rather than as a
tidy-up. Say the word and I will open it with the spec.

Closing as answered — reply and it reopens.