Plan the API version stamps' phase 2, task by task

[bjlittle]

The implementation plan for phase 2 of #227's API version stamps, specified in #331 (stamps spec). Plan only — the build follows as its own pull request and closes #227. The build must merge before the v0.1.0 release candidate, whose merge-back would otherwise turn main red.

The five tasks

#	Task	Holds it
1	The snapshot rule: read_snapshot, render_snapshot, and a recorded argument to check_versionadded	a test per row of the rule, a malformed line refused rather than skipped, and three mutations — the snapshot half removed, the target half weakened, a bad line skipped
2	The --write-snapshot command, which refuses while a stamp fails or no version can be derived	tests over a monkeypatched surface, a real run that writes nothing, and a mutation of the refusal
3	The version test, and the setuptools_scm scheme it depends on	an integration test that builds a repository and walks it through stamps spec §1's and §3.4's tables, including the branch-name trap
4	The policy in docs-style.rst, runbook steps 4 and 10, and the retired Two gates will move at the first tag note	two tests, the docs build and its five gates, and a mutation
5	Verify the branch and hand over the finish	pixi run tests, lint, docs, and no snapshot committed

The plan commits no .github/api-surface.txt: the first snapshot is written at the release candidate's freeze, by runbook step 4.

What planning measured first

• main() takes no arguments today, and two tests call it. A parser reading sys.argv would be handed pytest's own arguments there, so main takes an explicit argv that defaults to empty.
• A pyproject.toml holding only [tool.setuptools_scm] is enough for setuptools_scm to derive the scheme's versions in a temporary repository, so Task 3's test builds one from the committed manifest's table.
• Task 3 moves a quoted count. Its test stands down without a repository, so floors spec §3.3's "Forty-one" becomes forty-two, as Leave what a release moves out of the container census #325's test moved it before. Task 3 runs that gate before and after the change.

How the plan's code was checked

Once merged, a plan is checked by nothing, so this one was run before it was proposed. A driver took every code block from the plan file and applied them task by task to a throwaway worktree of main at b8e5cb1. It ran each step's own commands — tests, lint, commits and mutations — against the installed pixi environments.

The first run found three lint errors in the plan's code, and a second run from the corrected text was clean.

• ruff check rejected match="api-surface.txt:4", whose . is unescaped.
• It also rejected an unannotated *args: tests waive ANN001 but not ANN002.
• ruff format rewrote an 89-character assert.

An executor would have hit a failing hook at Task 1's first commit.

Checking every expectation against the runs found five more corrections:

• three -k filters select a test their expectation did not mention: scheme in Task 3, and runbook in Task 4's red run and in its mutation;
• Task 1's mutation (a) passes three tests its expectation left unstated;
• Task 1's red run names SNAPSHOT_HEADER, not SNAPSHOT or SnapshotError.

Every expected count now matches a measured one.

On the second run:

• Red states. Task 1: 13 failed, six TypeErrors and seven AttributeErrors. Task 2: 4 failed, three TypeErrors and a SnapshotError raised out of main. Task 4: 2 failed, 1 passed.
• Mutations. Task 1's (a), (b) and (c) failed 3, 1 and 4 tests. Task 2's refusal mutation and Task 4's runbook mutation each failed the test the plan names.
• The quoted count. The floors spec §3.3 gate failed before the change, counting 42 guarded tests against the specification's forty-one, and passed after it.
• Lint and tree. Every lint step passed with no file rewritten, and the tree was clean after every commit.
• The branch. The full suite passed (2326 passed, 6 skipped) and pre-commit run --all-files passed. The docs build succeeded with no warnings and all five gates passing. No .github/api-surface.txt was committed.

Not dry-run: runbook steps 4 and 10 themselves, which first run at the release candidate. Task 3's test pins the version behaviour they rely on, and Task 2 runs the command for real without writing.

The finish, left to the build's controller

File one issue for the two items #227 carries past phase 2 — versionadded to version-added once the Sphinx floor passes 9.0, and suggesting version-added to numpydoc's DIRECTIVES — and repoint stamps spec §8's Deferred item to cite it; open the build with Closes #227.

🤖 Generated with Claude Code

https://claude.ai/code/session_01C79QePZ862i61EJodupwVT

[read-the-docs-community]

Documentation build overview

📚 tephpy | 🛠️ Build #34579491 | 📁 Comparing ac5a81c against latest (b8e5cb1)

  🔍 Preview build  

9 files changed · ± 9 modified

± Modified

• sg_execution_times.html
• gallery/plot_hodograph.html
• gallery/plot_parcel_analysis.html
• gallery/plot_sounding.html
• gallery/plot_tephigram.html
• gallery/sg_execution_times.html
• reference/changelog.html
• reference/whatsnew/index.html
• reference/whatsnew/latest.html