Make a release a section of the changelog, not a second page title - #323
Merged
Merged
Conversation
The towncrier template underlined each release title with towncrier's
`top_underline`, which is `=` -- the same style
`docs/src/reference/changelog.rst` uses for its own title. docutils
reads heading levels from the order underline styles first appear, so
the release title became a *sibling* top-level section rather than a
subsection. The changelog document then had two top-level sections,
and `reference/index.rst`'s toctree listed the newest release beside
*Changelog* as though it were a page of its own:
Changelog -> changelog.html
v0.1.0.dev212+dirty (2026-09-14) -> changelog.html#v0-1-0-...
Spotted by Bill in the rendered site. :pull:`322`'s whole-branch review
did flag the second `<h1>`, and I parked it as cosmetic because the
build was clean -- it is not cosmetic, it reaches the navigation. That
was the wrong call, made on the wrong question: whether the build
passes, rather than what the page does.
The template now underlines with `-`, which nests correctly under the
page title and leaves the category headings' `^` a level below it
again. A standalone read of `CHANGELOG.rst` is unaffected: `-` is its
first underline style and so still its top level.
The new test states the invariant rather than the character -- the
release title must not share the page title's style -- and the old
test's underline assertion goes with it, since two tests asserting one
thing is how they drift.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PDtaSBAWHdYhYfyyWCcC5h
Named after the pull request now that it exists, rather than after the number that was free when the work started. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PDtaSBAWHdYhYfyyWCcC5h
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes a defect #322 shipped, spotted by @bjlittle in the rendered site.
What was wrong
The reference quadrant's toctree carried a ninth entry pointing into the changelog:
The towncrier template underlined each release title with towncrier's
top_underline, which is=— the same styledocs/src/reference/changelog.rstuses for its own title. docutils takes a document's heading levels from the order underline styles first appear, so the release title became a sibling top-level section rather than a subsection. The page then had two<h1>s, andreference/index.rst's toctree listed the newest release beside Changelog as though it were a page of its own.The fix
The template underlines with
-. That nests under the page title and leaves the category headings'^a level below it again. A standalone read ofCHANGELOG.rstis unaffected —-becomes its first underline style and so still its top level.Verified in the built site: the toctree is back to eight entries, the changelog page has one
<h1>, and the release heading is now an<h2>.Worth saying
#322's whole-branch review did flag this — "the release title renders as a second
<h1>… builds clean; it is a page-structure change §3.3 does not discuss". I parked it as cosmetic.That was the wrong call, and wrong on the wrong question: I weighed whether the build passed rather than what the page did. A clean fail-on-warning build says nothing about navigation, and this leaked straight into it.
The new test
It states the invariant rather than the character — the release title must not share the page title's underline style — and explains why
top_underlineis not used. The old test's underline assertion is removed with it: two tests asserting one thing is how they drift.pixi run tests2320 passed, 2 skipped; lint and docs clean.🤖 Generated with Claude Code
https://claude.ai/code/session_01PDtaSBAWHdYhYfyyWCcC5h