Skip to content

πŸ”§ fix(towncrier): match docstrfmt RST formatting expectations - #1002

Merged
gaborbernat merged 1 commit into
pypa:mainfrom
gaborbernat:fix-towncrier-docstrfmt
Mar 25, 2026
Merged

gaborbernat merged 1 commit into
pypa:mainfrom
gaborbernat:fix-towncrier-docstrfmt

Conversation

@gaborbernat

Copy link
Copy Markdown
Contributor

The release workflow at run 23517320705 failed with the environment inconsistency check because towncrier generates CHANGELOG.rst with asterisks for version headers and equals signs for section headers, but docstrfmt expects hash symbols for version headers and asterisks with overlines for section headers. 🎨 When the release script runs, towncrier creates the changelog, then pre-commit runs docstrfmt which reformats it, causing the consistency check to fail.

Configure towncrier to use hash symbols for version titles via top_underline = "#" and update the template to add overlines above section headers. This ensures the generated changelog matches docstrfmt expectations without requiring reformatting, allowing the release script to pass the environment consistency check.

The next pre-release workflow run will generate a properly formatted changelog that passes all pre-commit checks.

Towncrier generates CHANGELOG.rst with asterisks for version headers and
equals signs for section headers, but docstrfmt expects hash symbols for
version headers and asterisks with overlines for section headers. This
mismatch caused the release script to fail with the environment
inconsistency check after towncrier ran.

Configure towncrier to use hash symbols for version titles and update
the template to add overlines above section headers matching docstrfmt
output format. This ensures the generated changelog passes pre-commit
checks without modification.
@gaborbernat gaborbernat added the bug Something isn't working label Mar 25, 2026
@gaborbernat gaborbernat added the bug Something isn't working label Mar 25, 2026
@gaborbernat
gaborbernat merged commit 74ae997 into pypa:main Mar 25, 2026
65 checks passed
gaborbernat added a commit to gaborbernat/build that referenced this pull request Mar 30, 2026
The 1.4.2 entry was generated before the towncrier template fix (pypa#1002),
using * for version and = for sections instead of # and *. Also remove
stray "Changelog" header between 1.4.1 and 1.4.0.
gaborbernat added a commit that referenced this pull request Mar 30, 2026
The 1.4.2 entry was generated before the towncrier template fix (#1002),
using * for version and = for sections instead of # and *. Also remove
stray "Changelog" header between 1.4.1 and 1.4.0.
gaborbernat added a commit to gaborbernat/build that referenced this pull request Mar 30, 2026
The 1.4.2 entry was generated before the towncrier template fix (pypa#1002),
using * for version and = for sections instead of # and *. Also remove
stray "Changelog" header between 1.4.1 and 1.4.0.
gaborbernat pushed a commit to gaborbernat/build that referenced this pull request Apr 13, 2026
Every release since 1.4.1 produced a CHANGELOG entry whose heading
characters did not match prior entries, breaking sphinx -W with
"Inconsistent title style: skip from level 1 to 3" and pinning
Read the Docs' stable version at 1.4.0 since no tagged build after
that could complete.

The root cause is that `top_underline` has never been a towncrier
config key. The settings loader only reads `underlines`, and towncrier
passes `underlines[0]` into the template as the `top_underline`
variable. PR pypa#1002 added `top_underline = "#"` intending to drive the
version heading, but towncrier silently ignored it and kept emitting
`*` for the top line and `=` for sections, neither of which matched
the `#`/`*` hierarchy established by every historical entry. docstrfmt
then rejected the hybrid file, and the release script's first
pre-commit pass left the new entry half-rewritten.

Prepend `#` to `underlines` so towncrier feeds `#` as the top
underline and `*` as the section underline, matching the existing
changelog and docstrfmt's expectations. Rewrite the 1.4.3 entry to
the correct hierarchy so the current docs build succeeds without a
follow-up patch commit. Add a docs build step to the pre-release
workflow as a backstop so any future regression fails the run before
a tag is pushed.
@gaborbernat
gaborbernat deleted the fix-towncrier-docstrfmt branch July 10, 2026 18:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants