🐛 fix(release): detect pre-commit environment inconsistencies#1001
Merged
gaborbernat merged 2 commits intopypa:mainfrom Mar 24, 2026
Merged
🐛 fix(release): detect pre-commit environment inconsistencies#1001gaborbernat merged 2 commits intopypa:mainfrom
gaborbernat merged 2 commits intopypa:mainfrom
Conversation
The release commit bd88956 passed local pre-commit checks but failed pre-commit.ci because docstrfmt formatted CHANGELOG.rst differently in the tox release environment versus the CI environment. This happens when pre-commit hooks make changes after the final check_call run but before the commit, leaving unstaged changes that get caught by pre-commit.ci. Added --show-diff-on-failure to the final pre-commit run to display what changed if hooks fail. After the final run, verify the repository has no unstaged changes. If it does, fail with a clear error about environment inconsistency rather than creating a release commit that will fail CI.
Pre-commit.ci detected that CHANGELOG.rst was not formatted according to the docstrfmt hook configuration. The section headers use a different underline style than what docstrfmt expects. Reformatted the changelog to match the expected docstrfmt output to ensure pre-commit.ci checks pass on this PR.
43ff4f7 to
6ad6ae8
Compare
henryiii
approved these changes
Mar 24, 2026
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
2 participants
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.
The release commit bd88956 passed local pre-commit checks but failed pre-commit.ci because
docstrfmtformattedCHANGELOG.rstdifferently in the tox release environment versus the CI environment. 🔧 This happened becausetowncriergenerated RST with one header style (asterisks for versions, equals for sections) butdocstrfmtexpects a different style (hash symbols for versions, asterisks with overlines for sections).The fix has three parts:
Detect environment inconsistencies: Added
--show-diff-on-failureto the final pre-commit run and check for unstaged changes afterward. If pre-commit modifies files after the final run, the script fails with a clear error instead of creating a commit that will fail CI.Fix existing CHANGELOG formatting: Applied
docstrfmtformatting to the existing CHANGELOG.rst to match expected output.Fix towncrier template: Configure towncrier to generate CHANGELOG entries matching docstrfmt expectations by setting
top_underline = "#"and updating the template to add overlines above section headers.This ensures the release script will fail early if environment mismatches occur, and fixes the root cause by aligning towncrier output with docstrfmt requirements.