Leave what a release moves out of the container census

[bjlittle]

Closes #318.

What was wrong

Runbook step 3, pixi run changelog --version X.Y.Z, left the suite red. The container census recorded by #297 is keyed by file, and assembly deletes every fragment and writes its text into CHANGELOG.rst — so the citations are conserved and every key they sat under changes, on the commit that gets tagged:

CHANGELOG.rst spec-3-2: recorded 0, found 4
changelog/201.enhancement.rst spec-3-2: recorded 1, found 0
changelog/300.documentation.rst spec-3-2: recorded 2, found 0
changelog/90.documentation.rst spec-3-2: recorded 1, found 0

Re-measuring the issue body

Found by assembling --version 0.1.0 on a throwaway worktree of 9c694b5, not by reading:

• Four rows move, not one. The issue quoted the first line of the message above. Its option 1 — exclude CHANGELOG.rst — would have left the three fragment rows failing.
• Nothing else reads the assembled file. On that tree the census was the only failure across the suite (1 failed, 2285 passed), the fail-on-warning docs build and all five docs gates, and every pre-commit hook. The browser demo was not run; it does not read the changelog.

It is also step 3 now, not step 2: What's New inserted one ahead of it.

The fix

The census leaves out what a release moves: CHANGELOG.rst and every fragment. A fragment is recognised by towncrier's own rule — a configured type among the parts of its name after the first, as parse_newfragment_basename reads it — rather than by directory, so changelog/README.md and template.rst, which are hand-written and untouched by a release, stay counted. Measured rather than assumed: on main the predicate selects exactly the 176 files towncrier touched in the assembly, 175 deletions and one write.

The corpus is unchanged. Resolution, keying and separation (docs spec §3.6) still cover both — the published changelog renders these citations as links, and all of them pass on the assembled file.

What is given up is the census noticing a new fragment that cites a container. It has done that once, for the two in #300, and both were upheld.

The record loses three rows, four citations on spec-3-2, leaving 11, with a dated note. anchor spec §7's census item is tagged Refined with the reason, and whatsnew spec §5, which recorded the defect, records it resolved.

The new test

test_the_census_leaves_out_what_a_release_moves fails on main for exactly the three fragment rows. Its guard against passing vacuously — that something a release moves does cite a container — holds on both sides of a release: the fragments carry those citations before it and CHANGELOG.rst after. With the fix applied to the assembled tree, it and the census both pass there.

Two more edits it needed

• floors spec §3.3 says Forty-one, not Forty. It quotes how many tests stand down without a repository, and the new test is one of them — test_the_specification_quotes_the_number_of_repository_guarded_tests caught it.
• anchor spec §7's two references to Keep a census of the citations that name a subdivided section #297 were :pull: roles, which a MyST page renders as literal text rather than a link. They are {pull} now, confirmed as links in the built page. Two more specifications carry the same defect — tephpy-design.md and plotting-tour-design.md, one each, both confirmed literal in the build — and are not touched here: check_github_references.py passes an rst role in a MyST file, so that is A reStructuredText role in a MyST page renders as plain text, and the reference gate passes it #326 rather than a hand-fix here.

Filed along the way

#324 — released changelog entries stay under resolution, and nothing says whether a citation in released history may be edited when a section it names is removed or renumbered. Pre-existing, and not this change's to settle.

Verification

On 28e99ad: pytest --mpl 2289 passed, 6 skipped; a clean fail-on-warning docs build and all five docs gates pass; every hook passes on the changed files. CI is green.

🤖 Generated with Claude Code

https://claude.ai/code/session_01C79QePZ862i61EJodupwVT

[read-the-docs-community]

Documentation build overview

📚 tephpy | 🛠️ Build #34567105 | 📁 Comparing 28e99ad against latest (9c694b5)

  🔍 Preview build  

13 files changed · ± 13 modified

± 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-08-13-dependency-floors-design.html
• developer/specs/2026-09-09-reanchor-plotting-design.html
• and 3 more...