Skip to content

CI: Enforce the full-URL form for new GitHub references (GH#55461) - #67342

Open
jbrockmendel wants to merge 2 commits into
pandas-dev:mainfrom
jbrockmendel:bug-55461
Open

CI: Enforce the full-URL form for new GitHub references (GH#55461)#67342
jbrockmendel wants to merge 2 commits into
pandas-dev:mainfrom
jbrockmendel:bug-55461

Conversation

@jbrockmendel

Copy link
Copy Markdown
Member

Implements the pre-commit half of GH-55461, without the bulk rewrite.

GH-55461 converged 7-to-4 on the full-URL form for GitHub references, and the plan was "conforming the tests to URL - ideally with some form of pre-commit check". Conforming the tests turns out to be the expensive half: there are 12,145 short references in the tree, spelled 24 different ways, and 2,823 of the lines they sit on would exceed the line limit once a 44-character URL replaces GH#1234, so they would need their prose reflowed by hand. That is a lot of churn and git blame damage for no behaviour change.

The cheap half is worth having on its own, since it is what stops the spelling count growing to 25. This PR does only that:

  • scripts/validate_gh_references.py rejects a short-form reference (GH#1234, GH 1234, GH-1234, GH1234, gh-1234, GH: #1234, ...) and points at https://github.com/pandas-dev/pandas/issues/1234 instead.
  • scripts/gh_reference_baseline.txt grandfathers everything already in the tree: 9,043 distinct (file, issue number) pairs across 998 files. Keying on the issue number rather than the line means the baseline survives line moves and edits to the prose around a reference, so it only fires on a genuinely new one.
  • Renaming a file would otherwise orphan its baseline entry, so --update-baseline rewrites the file. It refuses to run when the total would grow, which lets it relocate grandfathered references but not silence new ones.
  • The hook excludes scripts/, because the checker and its tests have to spell out the forms they reject.

Deliberately not closing GH-55461: the bulk conform is still open, and whether it is worth doing is the call the issue was asking for. Merging this only fixes the format of new code.

Two things worth a look:

  • The separator class is narrow on purpose. Allowing _ would false-positive on identifiers such as gh_13141_expected in test_html.py, and allowing , would match CSV fixture rows like GH,100102040,jkl,0205 in test_dtypes_basic.py. Digits are capped at 2-6 with a trailing lookahead for the same reason.
  • Enforcing URL-only going forward leaves the codebase permanently mixed, which arguably makes grepping for a reference worse rather than better - two formats instead of one, where today there are six. Retargeting the hook at a canonical short form instead is a one-constant change, though the baseline would have to be regenerated against the 734 existing URL references.

AI disclosure: drafted with Claude Code (claude opus 5 (high)), which measured the corpus, wrote the checker and its 25 unit tests, and generated the baseline.

Adds a pre-commit hook rejecting short-form GitHub references (GH#1234,
GH 1234, pandas-devGH-1234, GH1234, pandas-devgh-1234, ...) in newly added code, in favour of
the full URL. The ~9k references already in the tree are grandfathered in
scripts/gh_reference_baseline.txt, so no bulk rewrite is needed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@jbrockmendel jbrockmendel added Testing pandas testing functions or related to the test suite CI Continuous Integration Code Style Code style, linting, code_checks labels Aug 30, 2026

@rhshadrach rhshadrach left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Enforcing URL-only going forward leaves the codebase permanently mixed, which arguably makes grepping for a reference worse rather than better

I don't think it makes it worse when compared to the status quo. But maybe that's a bit vacuous because there isn't a way forward that could possibly be worse than status quo 😆.

Of course agreed grepping is slightly worse than going with e.g. GH#1234, but I almost am always just grepping the number bit anyways and I find Ctrl-Click opening in the browser far more valuable. github.com/.*/\d+ is a reliable grep here but agreed it's tedious when compared to what's needed for the alternative.

Comment thread scripts/validate_gh_references.py Outdated
"""
for lineno, line in enumerate(content.splitlines(), start=1):
for match in SHORT_REF.finditer(line):
yield lineno, match.start(), match.group(0), match.group(1)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
yield lineno, match.start(), match.group(0), match.group(1)
yield lineno, match.start() + 1, match.group(0), match.group(1)

Columns are typically reported as 1-based I believe.

@jbrockmendel
jbrockmendel marked this pull request as ready for review August 30, 2026 19:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CI Continuous Integration Code Style Code style, linting, code_checks Testing pandas testing functions or related to the test suite

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants