GeezerVison is showing github.com — Add .mailmap Validation with mailmap-checker · Issue #148329 · python/cpython
Add .mailmap Validation with mailmap-checker #148329DescriptionFeature or enhancement
Proposal:
Proposal: Add .mailmap Validation with mailmap-checker
Summary
Add automated .mailmap validation to CPython's patchcheck.py and pre-commit configuration using the mailmap-checker tool, ensuring proper formatting, completeness, and preventing duplicate entries.
Background
The .mailmap file was introduced in PR #103696 to map contributor name/email changes in git history. As noted by @zware in that discussion:
"Since we've now started down this road, there may be other contributors who would like to be similarly added here..."
Currently, there's no automated validation, which can lead to:
- Syntax errors going undetected
- Unmapped contributor identities across email changes
- Duplicate or conflicting entries
- Manual maintenance burden
Proposed Solution
Use the existing mailmap-checker tool (https://github.com/cansarigol/mailmap-checker) which:
- Detects unmapped Git identities by scanning commit history
- Groups authors by email and local-part
- Validates
.mailmap syntax and completeness
- Can auto-fix and suggest entries
Implementation
1. Add to Tools/scripts/patchcheck.py:
def mailmap_checked():
"""Check if .mailmap is properly maintained."""
try:
subprocess.check_call(
['mailmap-checker', 'check'],
cwd=SRCDIR,
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL
)
return True
except subprocess.CalledProcessError:
print("Mailmap check failed. Run 'mailmap-checker check' to see details.")
return False
except (FileNotFoundError, OSError):
print("mailmap-checker not installed, skipping mailmap check.")
return True2. Add to .pre-commit-config.yaml:
- repo: https://github.com/cansarigol/mailmap-checker
rev: v1.0.0 # Use latest stable version
hooks:
- id: mailmap-check3. Update documentation:
Add to Doc/developers/patchcheck.rst or contributing guide:
Mailmap Validation
------------------
CPython uses `.mailmap` to consolidate contributor identities. To validate:
.. code-block:: bash
# Check for unmapped identities
mailmap-checker check
# Auto-fix (preview first)
mailmap-checker fix --dry-run
mailmap-checker fix Related
Has this already been discussed elsewhere?
This is a minor feature, which does not need previous discussion elsewhere
Links to previous discussion of this feature:
No response Activitycansarigol commented on Apr 10, 2026 This shows the current situation.
Details
StanFromIreland commented on Apr 10, 2026
Use the existing mailmap-checker tool (https://github.com/cansarigol/mailmap-checker) which:
This tool is a week old, (and I see you're the author?) IMO we'd have to audit it before adding it to pre-commit, since it is then automatically installed in many places. Reacted by 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) cansarigol commented on Apr 10, 2026 Yes, I'm the author. The tool originated from solving this exact problem at my company - tracking down scattered user identities across our Git history. After seeing similar gaps in large Python projects (including CPython's new .mailmap), I decided to make it public.
I completely understand the need for an audit before adopting external dependencies. StanFromIreland commented on Apr 10, 2026 Also, how does the tool pick what is 'canonical'? It got my name wrong, for example. StanFromIreland commented on Apr 10, 2026 cansarigol commented on Apr 10, 2026
Also, how does the tool pick what is 'canonical'? It got my name wrong, for example.
When no .mailmap entry exists, the tool picks the canonical using a heuristic: it prefers names that start with a letter and contain a space. Among equally valid names, it falls back to alphabetical order. This is a known limitation.
I'm open to improving the heuristic. One idea is to prefer the name with the most commits encukou commented on Apr 10, 2026 I don't think "scattered user identities" is a problem we need to solve. Also, changing peoples' names without their consent would be quite rude. Reacted by Hugo van Kemenade, Stan Ulbrych, Zachary Ware and 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) StanFromIreland commented on Apr 10, 2026 cansarigol commented on Apr 10, 2026
I see there is also an older, and a little more popular pre-commit hook that seems to do the same thing, https://github.com/jumanjihouse/pre-commit-hooks?tab=readme-ov-file#check-mailmap?
My main concern was auto-fix that automatically generates and inserts the missing entries. mailmap-checker supports committer identities and cross-domain grouping via email local-part matching. But logic is same as you said vstinner commented on Apr 10, 2026 The .mailmap file was created in 2023 and then only modified once in 2025. I don't think that we need a tool validating this file automatically, since it's almost never modified. We can use such tool manually when a future change will happen. Reacted by Stan Ulbrych, Hugo van Kemenade, 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) and Maurycy Pawłowski-Wieroński cansarigol commented on Apr 10, 2026 To clarify — the tool doesn't change anyone's name. It detects gaps in the existing .mailmap file that CPython already maintains since 2023. I understand that a pre-commit hook may be overkill for a file that's rarely modified. The tool can also be used as a one-off CLI command (mailmap-checker check) — no hook needed. StanFromIreland commented on Apr 11, 2026 Thanks for the suggestion @cansarigol, but unfortunately I'm going to close this issue. It is clear there is no support for this from the core team (if someone does, please re-open!).
It could be used as a one-off command, but that brings us back to Petr's point:
Also, changing peoples' names without their consent would be quite rude.
MetadataMetadataDevelopmentNo branches or pull requestsIssue actions
|