[LalatenduMohanty]

Merges the new-resolver-config feature branch into main. It implements the new resolver config proposal. Epic: #1254.

What it does

A package can now use one source: block instead of plugins and scattered settings. The block picks:

• how fromager finds versions (PyPI index, GitHub or GitLab tags)
• what it downloads (sdist, prebuilt wheel, tarball or git checkout)
• how it makes the sdist (pep517 or tarball)

Providers: pypi-sdist, pypi-prebuilt, pypi-download, pypi-git, github-tag-git, github-tag-download, gitlab-tag-git, gitlab-tag-download, hook-sdist, hook-prebuilt, not-available.

• source: works at the package and variant level. The variant wins.
• Mixing source: with old settings (resolver_dist, download_source, variant pre_built/wheel_server_url) is an error.
• bootstrap, build, build-sequence, build-parallel and download-sequence use the configured resolver.
• hook-sdist and hook-prebuilt let existing plugins keep working with source:.
• The build order records source_provider for each source: package.
• build-sequence and download-sequence check the recorded source_provider (fix(build-sequence): validate recorded source providers #1433).
• min_release_age (cooldown) works the same as with old settings.
• A new e2e test builds source: packages end to end (test(e2e): build packages with configured sources end to end #1412).
• package resolve, find-updates, list-overrides and list-versions use source: (feat(package): honor configured source resolvers #1407, fix(find-updates): honor configured source resolvers #1408, feat(list-overrides): surface source config in details output #1413).

Packages without source: work as before.

Breaking change

sources.download_source() now returns DownloadedSource (path and kind) instead of a Path, for all packages. Code that calls it must use .path.

Downstream plugins are not affected: plugins that implement the download_source hook still return a Path. Only one downstream script calls sources.download_source(), and the fix is to add .path to the call.

Pending, not blocking

These only affect packages that use source:.

Decide before 0.103.0 ships:

Issue	Work
#1440	Configured prebuilt wheels end up in wheels-repo/prebuilt instead of downloads in build commands

Follow-ups:

Issue	Work
#1416	Reject a non-hook source: when the package has resolver or download hooks
#1432	Prebuilt replay can leave the mirror serving an older wheel with the same name
#1388	Deprecation warnings for old settings
#1197	versionmap-git provider (open PR, needs rebase)
#1419, #1421, #1422, #1423	Smaller behavior fixes
#1420, #1424, #1425	Tests and docs
#1434	Shared Git checkout path helper

build-parallel does not check the recorded source_provider yet; the approach is still open.

Also tracked: #1395 and #1396 (prebuilt follow-ups) and #1257 (deferred).

Fixed since the last review: #1418 (#1433), #1430 (#1438) and #1431 (#1437).

🤖 Generated with Claude Code

[LalatenduMohanty]

@EmilienM Thanks. The find_source_dir() finding is confirmed. The same can happen on main with legacy archives, but #1441 made it possible for Git checkouts too. Fix in #1449: it tries names in a fixed order and only returns a nested directory that exists.

[dhellmann]

The implementation of this change is pretty complex. I think a lot of that is caused by not setting defaults "early" in the process of loading settings for a package, and so every point in the code that needs to figure out what to do for any aspect of processing a package has to manage all of the edge cases locally, instead of centralizing that logic. That also means it is harder to use patterns like Strategy to isolate each edge case, so we end up with a lot of if/then/elif statements or match statements to call variations of functions or instantiate classes.

If instead we took an approach that said the source: section of the config must be populated before we start processing a package, then we could inject the default settings into the config object. For packages that have no config file, we could inject them into a fake config object used at runtime. All of the rest of the logic throughout the other layers would then be simpler, because it could just instantiate the right kind of handler(s) and invoke them with a consistent API.

It is possible that this feature branch could be evolved in this direction, I don't know. I'll leave it up to the team to decide that.

This change also needs more user-facing documentation, with some how-to instructions with example configuration for different cases handled by the different types of providers and resolvers.

[LalatenduMohanty]

Thanks Doug — I think your diagnosis is right, and the review history of this PR is the best evidence for it. find-updates (#1408), list-versions / list-overrides (#1413) and package resolve (#1407) each needed a separate fix because every command re-implements the "is there a source: config?" branch, and each new entry point could miss it. There are about 15 of those branches in the final code.

The root cause is that we're deliberately supporting two systems at once. We can't drop the legacy settings yet because existing plugins and downstream configs depend on them, and the safety contract of this PR is "packages without source: work exactly as before." That's why hook-sdist and hook-prebuilt exist as bridge profiles — they let a plugin keep its hooks while moving its config to source:, one package at a time.

The good news is that most of those ~15 branches exist only to serve the legacy path. Once downstream plugins and settings have migrated to source:, we can delete the legacy branches and what's left is close to the model you're describing: every package has a populated source:, and the dispatch becomes "instantiate the handler for the profile" instead of per-site fallback checks. At that point the Strategy-style refactor is much smaller than it would be today.

So the plan I'd propose:

• Merge this branch as is — the dispatch points are all covered and tested, including the ones earlier review rounds caught.
• Drive migration after 0.103.0, using Warn users when legacy resolver settings are configured #1388 (deprecation warnings for old settings) to nudge packages over.
• Do the "populate defaults early" / handler refactor once legacy settings are gone or rare — tracked in Refactor: populate source: settings early and unify resolver dispatch #1451, so we only build the handler layer once.
• Add a user-facing how-to doc with example YAML for each provider before the release.

I'll answer the inline threads (step commands, provider match on replay) separately.

[LalatenduMohanty]

I have discussed with maintainers and we all agree to merge this and continue the development in main branch.

[mergify]

This pull request does not currently match the merge queue conditions, so it cannot be queued from here. The box comes back if it matches again.