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

[smoparth]

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]

📝 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

• X
• Mastodon
• Reddit
• LinkedIn

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

[rd4398]

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]

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

[LalatenduMohanty]

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

[dhellmann]

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]

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

[dhellmann]

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]

When I wrote "same providers with appropriate config," I was thinking of the case where a user could resolve the current HEAD to a known tag and passes that into the settings. I didn't mean to imply the existing providers support dynamic HEAD resolution out of the box. I'll update the proposal to make that distinction clear.

For supporting builds from branch HEAD directly, I think we'd want a new provider, something like git-branch that clones the repo first and discovers the version from package metadata. The source config proposal already mentions VCS support as future work in the git clone section, so a git-branch provider could fit naturally into that scope.

That said, I don't think we'd be able to support both building from HEAD and from a tagged release for the same package in the same run. The source config settings allows only one provider per package (or per variant).

The current req.url flow has the same limitation. If requirements.txt contains both mypkg==1.2.3 and mypkg @ git+https://...main, the bootstrap loop is keyed on (package_name, version). Whichever entry resolves first gets processed; the other is silently marked as "already seen" and skipped. The behavior is order-dependent.

There's also a cache staleness concern with branch HEAD builds. If the package uses a static version in pyproject.toml (not setuptools-scm or similar), then two different commits can produce the same version string and since fromager's wheel cache is keyed by (name, version), a rebuild the next day would find the cached wheel from the previous run and reuse it, even though the source has changed. This only works correctly when the version is dynamic and includes the commit hash (e.g., setuptools-scm producing 1.2.3.dev7+g3a4b5c6).

[dhellmann]

Yes, the whole URL based scheme was only designed to work for builds where the version was dynamically determined from the tag. If the project is not using a tag to set the version, then all bets are off.

Given that, I think the cache situation you raise is only a problem if the exact version specified in the build inputs is the same as the exact version that would be produced by the tag. In that case, it's not really a big deal because we only want one build anyway.

The feature was designed to be used in a completely separate pipeline build, though. Like having a new collection for nightly builds of projects. Those might not even necessarily go to the same place as a production build.

[smoparth]

Thanks, Doug! This is incredibly useful information. We'll review it during the next Fromager office hours and update you.

[dhellmann]

Sounds good, and to reiterate what I said elsewhere earlier today: I do think we should review whether this feature is useful enough to keep the code complexity. It's possible we could handle it a different way (a pre-processor to produce a config file or a different set of phase implementation functions are 2 ways), but it's also possible we could just delete the code and not worry about it.