docs(proposals): Deprecate PEP 508 Direct References (req.url) by smoparth · Pull Request #1225 · python-wheel-build/fromager

smoparth · 2026-07-02T14:57:35Z

Propose deprecating the package @ git+https://... syntax in favor of the declarative source provider config. The feature requires 19 special-case branches across 6 files and every use case is covered by the new git-clone providers (pypi-git, github-tag-git, gitlab-tag-git, versionmap-git).

Pull Request Description

What

Why

PR follows CONTRIBUTING.md guidelines

coderabbitai · 2026-07-02T14:58:01Z

📝 Walkthrough

Walkthrough

This change adds a new architecture decision record proposing deprecation and eventual removal of PEP 508 direct reference URL (req.url) support as a top-level bootstrap input. It defines scope limits, maps req.url use cases to declarative source provider configuration, and outlines a three-phase plan: emit deprecation warnings, provide migration guidance, and remove special-case code paths. No code or public API changes are included.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Sequence Diagram(s)

No diagram generated, as this change is a documentation-only addition with no code flow to depict.

Related issues: None mentioned in the provided context.

Related PRs: None mentioned in the provided context.

Suggested labels: documentation, proposal

Suggested reviewers: None specified.

🐰 A note is penned, no code to see,
Just plans for URLs' future decree,
"req.url", we bid adieu,
Sources will guide us through,
A rabbit's scroll of things to be.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
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.
Title check	✅ Passed	The title clearly states the main change: deprecating PEP 508 direct references (req.url).
Description check	✅ Passed	The description is directly about deprecating req.url in favor of declarative source providers.

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

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

rd4398 · 2026-07-02T15:06:49Z

This aligns with what we discussed earlier today. @dhellmann originally added this feature and we should wait for him to take a look and see what he thinks.

tiran · 2026-07-03T10:10:35Z

Nit-pick: We don't use the term "ADR" in upstream Fromager.

…(req.url) Propose deprecating the `package @ git+https://...` syntax in favor of the declarative `source` provider config. The feature requires 19 special-case branches across 6 files and every use case is covered by the new git-clone providers (pypi-git, github-tag-git, gitlab-tag-git, versionmap-git). Co-Authored-By: Claude <claude@anthropic.com> Signed-off-by: Shanmukh Pawan <smoparth@redhat.com>

LalatenduMohanty · 2026-07-07T20:50:12Z

I like this idea. This gives us an opportunity to cleanup the code

dhellmann · 2026-07-08T21:27:38Z

+
+## Why
+
+PEP 508 direct references (parsed into `Requirement.url` by the `packaging` library) let users specify a git URL inline in a requirement string. Fromager added this in [5f3fa68](https://github.com/python-wheel-build/fromager/commit/5f3fa68) (2025-02-22) to support building packages whose PyPI sdists were broken or unavailable.


We also added it to allow building from source for nightly builds, to differentiate from building only tagged versions of packages. We did that originally for one of our downstream apps that was regularly adding new dependencies when they did tag and we wanted to pull those dependencies into the nightly builds to catch issues before releases.

dhellmann · 2026-07-08T21:28:18Z

+
+PEP 508 direct references (parsed into `Requirement.url` by the `packaging` library) let users specify a git URL inline in a requirement string. Fromager added this in [5f3fa68](https://github.com/python-wheel-build/fromager/commit/5f3fa68) (2025-02-22) to support building packages whose PyPI sdists were broken or unavailable.
+
+This feature sits outside fromager's normal pipeline. Because the `Requirement` object carries the URL instead of a version specifier, every pipeline phase (resolution, download, prepare, build sdist) needs a separate `if req.url:` branch to bypass its normal logic. The codebase currently has **19 such branches across 6 files**. Each subsequent commit ([4a080bb](https://github.com/python-wheel-build/fromager/commit/4a080bb), [45008ce](https://github.com/python-wheel-build/fromager/commit/45008ce), [e50247d](https://github.com/python-wheel-build/fromager/commit/e50247d), [5687cf7](https://github.com/python-wheel-build/fromager/commit/5687cf7)) added special-case handling to accommodate `req.url` in a pipeline that wasn't designed for it.


This is a good reason to consider changing or removing this feature.

dhellmann · 2026-07-08T21:30:27Z

+| Build from GitHub tag | `pkg @ git+https://github.com/org/repo@v1.0` | `provider: github-tag-git` with `project_url` |
+| Build from GitLab tag | `pkg @ git+https://gitlab.com/org/repo@v1.0` | `provider: gitlab-tag-git` with `project_url` |
+| Build from specific commit | `pkg @ git+https://repo@abc123` | `provider: versionmap-git` with `versionmap` |
+| Build from branch HEAD | `pkg @ git+https://repo@main` | Same providers with appropriate tag/ref config |


This is the primary case we really cared about. Could you expand on the "same providers with appropriate config" explanation? How would we sometimes build from the HEAD of a branch and other times build a tagged version?

smoparth requested a review from a team as a code owner July 2, 2026 14:57

rd4398 requested a review from dhellmann July 2, 2026 15:07

smoparth force-pushed the docs/deprecate-req-url branch from 3e4eda9 to 4f97bed Compare July 6, 2026 14:42

smoparth temporarily deployed to release July 6, 2026 14:42 — with GitHub Actions Inactive

smoparth changed the title ~~docs(proposals): add ADR to deprecate PEP 508 direct references (req.url)~~ docs(proposals): Deprecate PEP 508 Direct References (req.url) Jul 6, 2026

smoparth mentioned this pull request Jul 6, 2026

Skip e2e and unit tests for docs-only changes #1230

Open

This was referenced Jul 7, 2026

docs: add git source URL examples to build-wheels documentation calungaproject/plumbing#318

Closed

Build from git calungaproject/index#4961

Merged

dhellmann reviewed Jul 8, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(proposals): Deprecate PEP 508 Direct References (req.url)#1225

docs(proposals): Deprecate PEP 508 Direct References (req.url)#1225
smoparth wants to merge 1 commit into
mainfrom
docs/deprecate-req-url

smoparth commented Jul 2, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jul 2, 2026 •

edited

Loading

Walkthrough

Sequence Diagram(s)

Uh oh!

rd4398 commented Jul 2, 2026

Uh oh!

tiran commented Jul 3, 2026

Uh oh!

LalatenduMohanty commented Jul 7, 2026

Uh oh!

dhellmann Jul 8, 2026

Uh oh!

dhellmann Jul 8, 2026

Uh oh!

dhellmann Jul 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants


		## Why

		PEP 508 direct references (parsed into `Requirement.url` by the `packaging` library) let users specify a git URL inline in a requirement string. Fromager added this in [5f3fa68](https://github.com/python-wheel-build/fromager/commit/5f3fa68) (2025-02-22) to support building packages whose PyPI sdists were broken or unavailable.


		PEP 508 direct references (parsed into `Requirement.url` by the `packaging` library) let users specify a git URL inline in a requirement string. Fromager added this in [5f3fa68](https://github.com/python-wheel-build/fromager/commit/5f3fa68) (2025-02-22) to support building packages whose PyPI sdists were broken or unavailable.

		This feature sits outside fromager's normal pipeline. Because the `Requirement` object carries the URL instead of a version specifier, every pipeline phase (resolution, download, prepare, build sdist) needs a separate `if req.url:` branch to bypass its normal logic. The codebase currently has 19 such branches across 6 files. Each subsequent commit ([4a080bb](https://github.com/python-wheel-build/fromager/commit/4a080bb), [45008ce](https://github.com/python-wheel-build/fromager/commit/45008ce), [e50247d](https://github.com/python-wheel-build/fromager/commit/e50247d), [5687cf7](https://github.com/python-wheel-build/fromager/commit/5687cf7)) added special-case handling to accommodate `req.url` in a pipeline that wasn't designed for it.

Uh oh!

Conversation

smoparth commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Description

What

Why

Uh oh!

coderabbitai Bot commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Sequence Diagram(s)

Uh oh!

rd4398 commented Jul 2, 2026

Uh oh!

tiran commented Jul 3, 2026

Uh oh!

LalatenduMohanty commented Jul 7, 2026

Uh oh!

dhellmann Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

dhellmann Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

dhellmann Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

smoparth commented Jul 2, 2026 •

edited

Loading

coderabbitai Bot commented Jul 2, 2026 •

edited

Loading