Write down how a release is cut, and what keeps going wrong

[ctgnz]

The retro's written output. Part of #144, and the companion to #148.

docs/releasing.md

2.0.0 took three tag cycles and two re-signed tags, and the runbook that eventually worked existed nowhere in the repo. This carries the sequence and, more usefully, the failures.

One cause explains three of the four: -Prelease runs only at tag time, so it drifts, and so does everything that only runs inside it.

failure	why nothing caught it
gpg: no default secret key	the workflow was copied from foxglove by #103; the four secrets were never created here, and no tag had run since
battleorder missing from the packaging matrix; two of four jars attached	both conditional on work that had landed months earlier
six dangling {@link}s to a renamed method	javadoc runs nowhere but -Prelease

And the fact that turned a workflow mistake into a re-signed tag: a re-run executes the workflow as it exists at the tagged commit, so you cannot fix it on master and re-run.

The doc also records the release-profile rehearsal that actually proves something — -Pstandard,release clean package without -Dmaven.javadoc.skip — since javadoc and GPG are the only two things the profile adds, and skipping both is what let the javadoc break through.

Written so hallux can follow it; little of it is jmsfx-specific.

README: three claims that outlived their condition

Same shape as the two exclusions this release found — nobody re-reads a comment.

• "JMSFX is not yet published to Maven Central, so build it from source" — false as of today, and the first thing a reader hits. Replaced with a Using it section: coordinates, the exactly-one-library constraint (discovery must fail rather than choose), and how to depend on the test jar when writing an extension library.
• "rasterises to PNG", twice — Compose SVG output without requiring the JavaFX toolkit #32 and Drop server-side PNG rendering #37 removed rasterisation entirely. Verified rather than assumed: zero matches in core and the server bar a logo image. The Building section already said "it deliberately does not rasterise", seventy lines below the claim.
• jmsfx-battleorder "documentation only … not yet in the reactor" — it is generated, in the reactor, and on Central.

Verification

mvn -Pstandard verify clean. Documentation only; no source or build changes.

🤖 Generated with Claude Code