Specify the API version stamps' phase 2

[bjlittle]

Specifies phase 2 of #227's API version stamps as a new living specification, stamps spec (docs/src/developer/specs/2026-09-15-api-stamps-design.md), and adds it to the specifications index. Specification only — the plan and the build follow as their own pull requests, and the build closes #227. It must merge before the v0.1.0 release candidate: without it the rehearsal's merge-back turns main red.

Why now

The gate's phase-1 rule — every published object cites the target, the base version the next tag will carry — is exact only while nothing has been released. Measured in a throwaway clone of main at 1ffb603, it stops being right at the first merge-back of any tag, a release candidate included, not at the release itself:

repository state	setuptools_scm	target	tests/test_api_docstrings.py
main, no tag	0.1.0.dev223	0.1.0	52 passed
tag v0.1.0rc1 on v0.1.x	0.1.0rc1	0.1.0	52 passed
main after merging v0.1.x back	0.2.0.dev2	0.2.0	3 failed

The failures are the hard-coded "0.1.0" in the version test, all 94 stamps ("cites 0.1.0, expected 0.2.0"), and main() returning 1 — over stamps that are all correct. The release runbook's Two gates will move at the first tag note had the timing wrong.

The design

• A committed snapshot, .github/api-surface.txt, written at the release freeze (runbook step 4) by check_api_docstrings.py --write-snapshot, which refuses to write unless every object passes and a target can be derived. An object it records keeps its recorded version; an object it does not record cites the target. The snapshot half needs no derived version, so it keeps working in shallow clones.
• No snapshot means phase 1, so the build can land before any tag.
• Removals are ignored until the next freeze rewrites the file; a renamed object is new and cites the target.
• The merge-back goes through a branch named merge-back (runbook step 10). An object merged into main after the release branch is cut must cite 0.1.0 before the merge-back and 0.2.0 after, and the target moves in the merge commit — a pull request from vA.B.x cannot contain the re-stamp, and main's protection requires the checks to pass.

Two things designing it got wrong first, both measured before this was written

1. The merge-back. The first draft said a mis-stamped new object could be re-stamped in the merge-back pull request. It cannot — the release branch does not contain it — which is the deadlock shape Let the pre-release note come out before the tag, not after #317 was. The dedicated branch is the fix.
2. The branch name. semver-pep440-release-branch reads any branch name containing a version as a release branch. Measured: merge-back-v0.1.x and merge-back/0.1 derive 0.1.0rc2.dev2 locally while pull-request CI derives 0.2.0.dev2 — a correct re-stamp would fail locally and pass in CI. merge-back and merge-back-release derive 0.2.0.dev2, agreeing with CI. §3.4 records the table, and a trap for whoever re-measures: tagging and merging with no commit on the release branch makes no merge commit and passes for the wrong reason.

Verification

On 427e8e4: every hook passes on the two changed files; tests/test_citations.py, tests/test_github_references.py, tests/test_docs_readingtime.py and tests/test_docs_landing_pages.py — 283 passed; a fail-on-warning docs build with no warnings, and check_rendered_citations.py and check_documentation_links.py both pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_01C79QePZ862i61EJodupwVT

[read-the-docs-community]

Documentation build overview

📚 tephpy | 🛠️ Build #34577772 | 📁 Comparing 9a3d3f6 against latest (1ffb603)

  🔍 Preview build  

13 files changed · + 1 added · ± 12 modified

+ Added

• developer/specs/2026-09-15-api-stamps-design.html

± Modified

• sg_execution_times.html
• gallery/plot_hodograph.html
• gallery/plot_parcel_analysis.html
• gallery/plot_sounding.html
• gallery/plot_sounding_comparison.html
• gallery/plot_tephigram.html
• gallery/sg_execution_times.html
• reference/changelog.html
• developer/specs/2026-09-14-whatsnew-design.html
• developer/specs/index.html
• and 2 more...