Tracking new source config wiring issues #1254

Epic: Wire new source: resolver config (backward compatible)

Branch: new-resolver-config
Proposal: New resolver and download configuration
Data model PRs: #1228 (resolver provider and requirement), #1235 (download method)

Overview

Wire the new source: config into the runtime pipeline alongside the legacy settings. Packages that declare source: use the configured resolver; packages without it keep the legacy behavior.

Non-goals: Deprecation warnings, removal of legacy code, and migration tooling.

Architecture

When source: is configured, resolution selects a provider through source_resolver and source download uses that resolver's download() method. The download result carries both the artifact path and its DownloadKind. Preparation and sdist building use that information and the resolver's build strategy. For prebuilt profiles, bootstrap must skip source-build phases and use the selected resolver to download a fresh wheel; this path is under review in #1208 / PR #1393. Packages without source: continue through the legacy settings and hooks.

Branch maintenance (complete)

• Add CI check to detect main → new-resolver-config merge conflicts #1295 — Detect main → new-resolver-config merge conflicts in CI.

Phase breakdown

Phase 1: Activate the model and validate settings (complete)

Load source: on package and variant settings, expose PackageBuildInfo.source_resolver, and reject mixed new and legacy source settings, including conflicts across package and variant levels.

• Activate source field on PackageSettings/VariantInfo and add source_resolver PBI property #1291 — Activate source and the PBI property.
• Add mutual exclusivity validator for source vs legacy fields #1207 — Validate source versus legacy settings.
• [Bug: new-resolver-config feature branch] Reject source and legacy settings mixed across package and variant levels #1368 — Reject cross-level source and legacy setting conflicts.

Phase 2: Resolution dispatch (complete)

Configured profiles select their resolver provider; packages without source: retain legacy resolution.

• Add source_resolver dispatch to resolution pipeline #1292 — Dispatch configured source resolvers.
• Implement hook-backed source resolver providers #1324 — Implement hook-backed resolver providers.

The hook URL contract is tracked in #1373.

Phase 3: Source download dispatch (complete)

Configured profiles use source_resolver.download(); packages without source: retain legacy source download.

• Add source_resolver dispatch to download pipeline #1293 — Dispatch source downloads.

The question of which selected-candidate data reaches download is tracked in #1384.

Phase 3b: Typed download result and hook compatibility (complete)

Use DownloadedSource to carry the path and kind, with documented compatibility for legacy download hooks.

• Introduce typed download-result and hook compatibility contract #1331 — Introduce the typed result and hook compatibility contract.

The remaining hook-profile combination is tracked in #1387.

Phase 4: Git preparation and sdist building

Git checkouts are prepared as directories. The resolver's build_sdist strategy selects PEP 517 or tarball behavior where an sdist build applies.

• Complete: Wire prepare_source and build_sdist for git-clone-based source resolvers #1205 (prepare Git checkouts), build_sdist uses tarball instead of PEP 517 #1206 (sdist build strategy), AbstractResolver does not enforce build_sdist #1256 (model contract for build_sdist).
• Open: Always clone submodules for new source resolvers #1210 (clone submodules for new Git source resolvers).

Phase 5: Prebuilt selection and wheel download (in review)

pypi-prebuilt and hook-prebuilt must skip source-build phases. When a fresh wheel is needed, bootstrap and later build commands must use the selected resolver's download contract. Legacy prebuilt behavior must continue to work.

• Route configured prebuilt profiles through bootstrap and wheel downloads #1208 — Route configured prebuilt profiles through bootstrap and wheel downloads.
• PR #1393 — implementation under review. The selected-wheel reuse question remains in its review thread.

Phase 6: Source type reporting (open)

• Record configured source provenance and download configured sources in download-sequence #1209 — Make get_source_type() report the actual source type for new resolver config, including Git checkouts recorded in build order.

Phase 7: Cooldown integration (open)

• New source config cooldown path has gaps compared to legacy resolve_package_cooldown() #1252 — Match legacy behavior for unset versus zero release age, global cooldown inheritance, top-level exact pins, and a shared bootstrap timestamp.

Phase 8: Command integration (open)

• Update CLI commands to display and use new source resolver config #1294 — Update package info, find-updates, list-overrides, and build command paths to use or display configured source resolvers.

The former Phase 9 issues are listed with their owning paths above: #1368 in Phase 1, #1256 and #1210 in Phase 4, and #1252 in Phase 7.

Hook and download contract work

• [Question] Clarify new resolver config hook source URL behavior and clean up the resolver provider contract #1373 — Decide how hook-sdist and hook-prebuilt use a source URL, preserve compatibility with existing hooks, and remove a hook-specific argument from unrelated resolver providers.
• [Question] Clarify what resolution data is available to source download #1384 — Clarify which data from the selected resolver candidate is available to download(); today the selected candidate is reconstructed from retained URL and version data.
• Allow hook profiles to use standard resolution with a custom download hook #1387 — Support a custom download hook with standard resolution for both hook profiles, and document which hook methods are optional. This is part of completing the hook-profile behavior.

Current work map

Arrows show the runtime path or the part of that path affected by remaining work. They do not declare every issue a merge dependency.

flowchart TD
    A["Done: config and validation<br/>#1291 #1207 #1368"] --> B["Done: resolution<br/>#1292 #1324"]
    B --> C["Done: source download<br/>#1293 #1331"]
    C --> D["Done: prepare and build sdist<br/>#1205 #1206 #1256"]

    C --> E["In review: prebuilt path and wheel download<br/>#1208 · PR #1393"]
    B --> F["Open: cooldown<br/>#1252"]
    C --> G["Open: source reporting and commands<br/>#1209 #1294"]
    C --> H["Open: Git submodules<br/>#1210"]
    B -.-> I["Contract work<br/>#1373 #1384 #1387"]

Follow-ups and deferred work

• Avoid repeated full copies when staging hook-prebuilt wheels #1395 — Avoid repeated full copies when staging unchanged hook-prebuilt wheels. Tracked as a follow-up to fix(resolver): honor configured prebuilt wheel resolvers #1393.
• Remove the prebuilt download dependency from wheels to sources #1396 — Remove the prebuilt download dependency from wheels to sources while preserving the hook-returned path contract. Tracked as a follow-up to fix(resolver): honor configured prebuilt wheel resolvers #1393.
• Separate resolution and download concerns in resolver providers #1257 — Separate resolution and download responsibilities in resolver providers. Deferred design improvement.
• Warn users when legacy resolver settings are configured #1388 — Warn about explicitly configured legacy resolver settings. Tracked separately because deprecation warnings are a non-goal here.

How to contribute

1. Pick an open issue whose relevant path is already wired.
2. Branch from new-resolver-config and target that branch with the PR.
3. Keep configured-source and legacy behavior covered by focused tests.