[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]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: f22a58e5-5e17-47bd-9384-1c8d7216fbeb

📥 Commits

Reviewing files that changed from the base of the PR and between 92d123b and 42ad37b.

📒 Files selected for processing (3)

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

✅ Files skipped from review due to trivial changes (3)

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

---

📝 Walkthrough

Walkthrough

This PR adds documentation: it registers a new proposal wheel-build-tag-hook in the proposals index, adds docs/proposals/wheel-build-tag-hook.md describing a fromager.hooks stevedore hook (wheel_build_tag) with its runner contract, inputs/outputs, validation rules, examples, and entry-point instructions, and updates docs/spelling_wordlist.txt to include libtorch and stdlib.

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 accurately summarizes the main change: adding a proposal for a wheel_build_tag hook to generate unique wheel file names.
Description check	✅ Passed	The description clearly relates to the changeset by explaining what the proposal adds and references the relevant issue #1059.
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.

[dhellmann]

What is the use case for having multiple hooks?

[tiran]

• The other hooks also support multiple hook implementations.
• Downstream can define multiple hooks, e.g. one for platform tag, one for Torch, one for each accelerator stack, and so on.

[dhellmann]

The way the other hooks are invoked only allows for one entry point, based on the package name. Stevedore should report an error if multiples are registered. For example, it wouldn't make sense to have 2 plugins give resolver providers for the same package.

This case feels different, because the hooks might combine data usefully. I'm just wondering if that's a "maybe useful" thing or a "definitely useful" thing, because the sorting seems complex to get right.

If we have 1 hook and it returns a list, then it can understand the ordering itself without leaking implementation details between hooks. But if we allow mixing hooks from multiple sources, how would we ensure that their sort ordering makes sense? I could see us releasing a bunch of simple hooks upstream, for example, to do platform tags and change log length and maybe other values. But how would we ensure those sort properly without having them all know about each other to specify their sort order values? And how would we add the one for torch into that mix without upstream and downstream knowing about each other in some meaningful way?

If instead of supporting multiple hooks, we just provide helper functions, then the single downstream hook implementation could specify the ordering.

If we want multiple hooks, then maybe we need a config setting to manage the order, instead of having the hooks try to express it directly? Stevedore has a way to invoke plugins based on a list of names, for example, so we could directly convert a list of names in a config file into invocation of the hooks in the expected order.

[tiran]

It's "maybe useful". We can get by with just a single hook. It would simplify the implementation, too.

I designed the feature with multiple hooks in mind to give us more flexibility and because stevedore may return multiple hooks. We do not need that flexibility in downstream. There seems to be no option to enforce a single wheel_build_tag entry point for fromager.hooks. Multiple packages can provide a wheel_build_tag hook.

Maybe entry points and stevedore extensions are the wrong approach for hooks that are singletons? This feature feels less like a notification hook and more like a setting. We could take another approach like a global config setting of type ImportString.

# overrides/settings.yaml
[wheels]
build_tag_hook = "mysettings.hooks:custom_tag_hook"

[dhellmann]

It looks like for overrides we're using a normal ExtensionManager and relying on only having one plugin with a given name. That's a bug, we should at least register a conflict_resolver function. Maybe just using the builtin error_on_conflict is what we want?

For hooks, it may make sense to have multiple values registered. If we use multiple hooks, I recommend building some sort of determinism into the execution order of the hooks themselves, though, rather than relying on the data returned by the hooks to be mixable directly. For example, in this case if you sorted by (name, order-key, value) then even if 2 hooks return the same order-key the results would always come out in the same order.

If we want a singleton hook, using the NamedExtensionManager or DriverExtensionManager may fit that pattern better.

[tiran]

Does it even make sense to use an entry point and stevedore hook for this feature? The wheel build tag hook feels like a runtime configuration option.

[dhellmann]

That's fair. It breaks the pattern we use elsewhere, but maybe since it's just one it does make sense.