Document the release process

[shnapz]

Summary

The README's release section was four paragraphs covering the happy path. It omitted every step and hazard that has actually bitten us, and one of its two verification links (https://oss.sonatype.org/) now returns HTTP 404 since legacy OSSRH was sunset.

Adds docs/releasing.md — prerequisites, choosing a version number, step-by-step, what the workflow does under the hood, known issues, recovery, and the manual fallback. The README section becomes the quick version plus a pointer.

Gaps this closes

Each of these has cost us time on a previous release:

• The -SNAPSHOT in pom.xml is not an input. v0.10.29 was cut from a tree reading 0.10.28-SNAPSHOT and published 0.10.29 silently. The next development version is derived from the release version too, not from the POM — so the field commits us to nothing and editing it before a release changes nothing.
• The version input is unvalidated and Maven Central is immutable. A typo is published permanently. The highest-risk step in the process carried no warning.
• The workflow does not create the GitHub Release. Done by hand it has twice been left flagged as a pre-release — revert prerelease #1011 ("revert prerelease"), and v0.10.30 sat flagged for three months, so the releases page and README badge advertised v0.10.29 while Central served v0.10.30.
• Auto-generated notes only enumerate PRs. A squashed cycle collapses to one bullet: v0.10.30's ~30 commits were all in Bump dependencies, JUnit 5, Java 25, Beam 2.74.0 #1039, and the generated notes mentioned neither the Java 8 drop nor the SLF4J 2.x migration.
• <scm><tag> is restored from the backup POM rather than computed, so a revert can bake in a stale literal that replays forever (Restore HEAD sentinel in scm tag #1044).
• The v0.10.29 tag does not point at the commit its artifacts were built from (e032ae1 vs 558b87a).
• e2e tests do not run during a release — e2e/e2e.sh is only invoked by maven.yml.

Also documents stale config that is inert but confusing: maven.yml's deploy job is if: false and references a github-settings.xml that does not exist; sonatype-settings.xml's header describes Travis; nexus-staging-maven-plugin is declared only to disable itself (and keeps attracting Dependabot PRs, e.g. #1013); .github/release-drafter.yml has no workflow to run it; distributionManagement still points at dead OSSRH endpoints.

Notes

• Docs only — no build or source changes.
• Best reviewed as the rendered docs/releasing.md.
• Facts were verified against the current repo and the published artifacts rather than from the existing docs. Several claims in the old README did not survive that check.
• Stacked conceptually on Restore HEAD sentinel in scm tag #1044 (the <scm><tag> fix), but there is no file overlap and the two can merge in either order.

Test plan

• docs/releasing.md renders; in-page anchors (#known-issues, #recovery) match headings
• README's relative link to docs/releasing.md resolves
• A maintainer who has cut a release confirms the mechanics section matches reality

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.87%. Comparing base (ca54576) to head (44cf85f).
⚠️ Report is 3 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff            @@
##             master    #1045   +/-   ##
=========================================
  Coverage     91.87%   91.87%           
  Complexity      288      288           
=========================================
  Files            27       27           
  Lines          1034     1034           
  Branches         90       90           
=========================================
  Hits            950      950           
  Misses           55       55           
  Partials         29       29           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.