Normalize the changelog style and introduce sphinx extlink roles #2202
Conversation
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
This changes the link format and does some regex-based rewriting of
the changelog to try to normalize the format a bit.
The conversion script was:
```python
import re
with open("CHANGELOG.md") as f:
content = f.read()
issue_link_pattern = re.compile(
r"\[#(\d+)]\(https://github.com/jazzband/pip-tools/issues/(\d+)\)"
)
pr_link_pattern = re.compile(
r"\[#(\d+)]\(https://github.com/jazzband/pip-tools/pull/(\d+)\)"
)
user_thanks_pattern = re.compile(r"Thanks(\s+)@([\w-]+)")
user_ref_pattern = re.compile(r"(\s+)@([\w-]+)")
date_pattern = re.compile(
r"^(\d{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4})$",
flags=re.MULTILINE,
)
redent_user_thanks_pattern = re.compile(r"([^\s]) Thanks {user}")
trim_newline_link_pattern = re.compile("\n\\s+(\\({(pr|issue)}`\\d+`\\)\\.?)\n")
content = issue_link_pattern.sub(r"{issue}`\1`", content)
content = pr_link_pattern.sub(r"{pr}`\1`", content)
content = user_thanks_pattern.sub(r"Thanks {user}`\2`", content)
content = user_ref_pattern.sub(r"\1{user}`\2`", content)
content = redent_user_thanks_pattern.sub("\\1\n Thanks {user}", content)
content = trim_newline_link_pattern.sub(" \\1\n", content)
content = date_pattern.sub(r"*\1*", content)
with open("NEW_CHANGELOG.md", "w") as f:
f.write(content)
```
- put backticks around commands, flags, and command fragments (e.g., filenames) - fix PR and issue links not previously captured - normalize the "Thanks" line style -- no trailing period, no extra words
|
@sirosen could you integrate |
|
Yep, happily done! I like Looks like the linkcheck lint is bothered by routing through the sponsors redirects, but that should be easy to handle with |
|
Ah, I tried fixing the redirects and now I get rate limited by GitHub (which is fair!); I see other projects are just skipping validation of the GitHub links and I'll configure the same for us. |
|
Yeah, I've actually put sphinx-issues into the towncrier issue, but it's the last item in there 😂 |
webknjaz
reviewed
Jul 14, 2025
Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) <[email protected]>
These links are too numerous in the changelog and result in rate limiting when `linkcheck` is run. Also, several users have changed their usernames in the years since their contributions, so checking those links fails. (And although we could update old changelog items, it's not clear that we should.)
sirosen
force-pushed
the
use-sphinx-issue-roles
branch
from
14c8c91 to
e072fb9
Compare
webknjaz
approved these changes
Jul 15, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
This is an early preparatory move for using towncrier.
Configuring it well (e.g., as in
cheroot) will probably involve integrating these link styles into our templates, which we can only do if we have these link styles available.This change is broken into two commits.
The first is the addition of
sphinx.ext.extlinks+ config + an automated rewrite of the changelog to normalize a lot ofstylistic elements and use
{issue}style and similar.123The second is a "manual fixup" (mostly done with editor commands and a bit of manual review) and is separated out to make the changes more visible in review.
The goal here is just to get some stylistic uniformity, especially for the really old changelog entries, so that editor highlighting won't be confused and we'll have a clearer claim to a consistent style.
In this phase, I'm more interested in having a consistent style than in exactly what that style is.
I can make small adjustments if anything is objectionable, but I'd rather save further rewrites (e.g., "should we replace those
Thanks $USERlines with anAUTHORSfile?") for future discussion and debate.For review of how this renders, here's the result before and after on two different chunks of the changelog:
Contributor checklist
Included tests for the changes.N/AMaintainer checklist
backwards incompatible,feature,enhancement,deprecation,bug,dependency,docsorskip-changelogas they determine changelog listing.