[proposal] wheel_build_tag hook for unique wheel file names

[tiran]

Pull Request Description

What

Add proposal document for a new hook point that injects platform, accelerator, and ABI suffixes into wheel build tags.

Why

See: #1059

• PR follows CONTRIBUTING.md guidelines

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR introduces a new proposal document for a build_tag_hook global configuration option that allows injecting deterministic suffix segments into wheel build tags. The hook receives context, requirement, version, and wheel tag information, returns a sequence of strings joined with underscores, and is subject to strict character validation ([a-zA-Z0-9.]). The proposal defines allowed inputs (context, requirement, wheel tags, immutable environment/platform data) and forbidden inputs (wheel content, build environment, ELF info) to ensure identical behavior across fresh and cached builds. The document includes a reference implementation, worked examples, and acknowledges current wheel format limitations. Supporting changes add libtorch and stdlib to the spelling wordlist.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: adding a proposal document for a wheel_build_tag hook to generate unique wheel filenames.
Description check	✅ Passed	The description is related to the changeset, explaining what is being added (proposal document) and why (references issue #1059) with proper acknowledgment of guidelines.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/proposals/wheel-build-tag-hook.md`:
- Around line 121-124: The example hook uses the variable parts when appending
CUDA tag but the accumulator defined earlier is named result, causing an
undefined variable error; update the CUDA branch to append to result (i.e.,
replace parts.append(...) with result.append(...)) and verify other branches
consistently use the same accumulator (referencing ctx.variant and Version(...)
in the function).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 243b235f-4791-4b2e-bff6-6ba1ef0f1db7

📥 Commits

Reviewing files that changed from the base of the PR and between 297ed76 and 20d94ef.

📒 Files selected for processing (3)

• docs/proposals/index.rst
• docs/proposals/wheel-build-tag-hook.md
• docs/spelling_wordlist.txt

[rd4398]

This is a solid design and will really help us downstream as well!

I left a few comments, after addressing those we can merge this.

[rd4398]

This looks good to me! I will wait for @LalatenduMohanty and @dhellmann to take a look as well and give feedback.

[mergify]

This pull request has merge conflicts that must be resolved before it can be merged.
@tiran please rebase your branch.

[dhellmann]

This looks good to me. I have a one clarifying question, but nothing to really hold it up.

[tiran]

I have re-designed the hook. It's now a single hook that is configured in global settings.yaml.

[dhellmann]

This direction makes sense to me. I'll leave the PR open for other reviewers to have a chance to read it before we merge it.

[tiran]

@dhellmann @rd4398 @LalatenduMohanty Could you please review the design again? Thanks!

[rd4398]

This looks good to me!

[LalatenduMohanty]

I feel this proposal is little verbose. We can make it concise without loosing important context.

[tiran]

I feel this proposal is little verbose. We can make it concise without loosing important context.

I have shortened the proposal and moved the example to a separate file. The file is included when Sphinx renders the markdown file.

This is an old review as per the latest comment from Rohan.