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 + req), #1235 (download method)

Overview

Wire the new source: config (Pydantic models in _resolver.py) into the runtime pipeline alongside the existing legacy settings. Packages that declare source: use the new system; packages without it keep existing behavior unchanged.

Non-goals for this epic: Deprecation warnings, removal of legacy code, migration tooling.

Architecture

Each pipeline function gets a dispatch check:

pbi = ctx.package_build_info(req)
if pbi.source_resolver is not None:
    # new path: use source_resolver.resolver_provider() / .download()
else:
    # legacy path: unchanged (resolver_dist, download_source, hooks)

Branch Maintenance

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

Phase Breakdown

Phase 1: Activate model + PBI property (critical path — blocks everything)

Uncomment source: SourceResolver | None on models, add source_resolver property to PBI, add mutual-exclusivity validator, export SourceResolver.

Files: _models.py, _pbi.py, __init__.py

Issues:

• Activate source field on PackageSettings/VariantInfo and add source_resolver PBI property #1291 — Activate source field and source_resolver PBI property
• Add mutual exclusivity validator for source vs legacy fields #1207 — Add mutual exclusivity validator for source vs legacy fields

Phase 2: Resolution dispatch

In sources.resolve_source() / get_source_provider(): if pbi.source_resolver, call source_resolver.resolver_provider() + find_all_matching_from_provider(). Legacy path unchanged.

Files: sources.py
Depends on: Phase 1

Issues:

• Add source_resolver dispatch to resolution pipeline #1292 : Add source_resolver dispatch to resolution pipeline
• Implement hook-backed source resolver providers #1324 : Implement hook-backed source resolver providers

Phase 3: Download dispatch

In sources.download_source(): if pbi.source_resolver, call source_resolver.download(ctx, req, candidate). Legacy path unchanged. Open design question: how to bridge the current download_url: str parameter with the new Candidate object.

Files: sources.py, bootstrapper callers
Depends on: Phase 1

Issues:

• Add source_resolver dispatch to download pipeline #1293 — Add source_resolver dispatch to download pipeline

Phase 3b: Typed download result contract

Replace the temporary (Path, DownloadKind) tuple with a stable typed result and define compatibility behavior for legacy download hooks.

Files: source artifact types, _resolver.py, hook documentation
Depends on: Phase 3

Issues:

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

Phase 4: Prepare + build_sdist for git checkouts

Handle DownloadKind.git_checkout in prepare_source() (skip unpack) and read source_resolver.build_sdist in build_sdist() (pep517 vs tarball).

Files: sources.py, bootstrapper/_prepare_source.py
Depends on: Phase 3b

Issues:

• Wire prepare_source and build_sdist for git-clone-based source resolvers #1205 — Wire prepare_source and build_sdist for git-clone-based source resolvers
• build_sdist uses tarball instead of PEP 517 #1206 — build_sdist uses tarball instead of PEP 517

Phase 5: Pre-built detection in bootstrapper

Check pbi.source_resolver.resolves_prebuilt_wheel in _resolve_and_extend(). Legacy path continues using pbi.pre_built.

Files: bootstrapper/_bootstrapper.py, wheels.py
Depends on: Phase 1

Issues:

• Wire pypi-prebuilt source resolver into bootstrapper pre-built detection #1208 — Wire pypi-prebuilt source resolver into bootstrapper pre-built detection

Phase 6: Source type mapping

Derive SourceType from source_resolver properties when present. Decision needed: re-add SourceType.GIT?

Files: sources.py, requirements_file.py
Depends on: Phase 1

Issues:

• Update get_source_type() to report correct source type for new source resolver config #1209 — Update get_source_type() to report correct source type for new source resolver config

Phase 7: Cooldown integration

New resolvers already pass _cooldown to providers internally. Ensure resolve_package_cooldown() isn't double-applied. Fix CooldownMixin None-vs-0 bug.

Files: _resolver.py, sources.py
Depends on: Phase 2

Issues:

• New source config cooldown path has gaps compared to legacy resolve_package_cooldown() #1252 — New source config cooldown path has gaps compared to legacy resolve_package_cooldown()

Phase 8: Command integration

Update package info, find-updates, list-overrides to display/use new source config.

Files: commands/package.py, commands/find_updates.py, commands/list_overrides.py
Depends on: Phase 2 + 3

Issues:

• Update CLI commands to display and use new source resolver config #1294 — Update CLI commands to display and use new source resolver config

Phase 9: Model-layer bug fixes (independent after Phase 1)

Issues:

• AbstractResolver does not enforce build_sdist #1256 — AbstractResolver does not enforce build_sdist
• New source config cooldown path has gaps compared to legacy resolve_package_cooldown() #1252 — CooldownMixin._cooldown conflates None/0
• Always clone submodules for new source resolvers #1210 — Always clone submodules for new source resolvers

Parallelism Map

                    Phase 1 (critical path)
                         |
          +------+-------+--------+----------+
          v      v       v        v          v
       Phase 2  Phase 3  Phase 5  Phase 6  Phase 9 (bugs)
          |       |
          v       v
       Phase 7  Phase 3b
          |       |
          |       v
          |    Phase 4
          |       |
          +---+---+
              v
           Phase 8

5 work streams can run in parallel after Phase 1 merges.

Deferred

• Separate resolution and download concerns in resolver providers #1257 — Separate resolution and download concerns in resolver providers (design improvement, not blocking)

How to Contribute

1. Pick a phase whose dependencies are merged
2. Create a feature branch from new-resolver-config
3. Follow the dispatch pattern: if pbi.source_resolver is not None → new path, else → legacy path
4. Add tests for both paths (new config + legacy config)
5. PR targets new-resolver-config branch