Codebase Layout

Production Source Tree

Production release code lives in src/buildish_release_tooling/release/. The CLI and documented file contracts are supported integration surfaces; Python module paths are internal.

Provider-neutral core

• core/config.py defines component identity, source policy, lifecycle, candidate policy, artifacts, signing, publication composition, and tags.
• core/models.py, core/state.py, and core/naming.py derive provider-neutral release identity and state.
• core/manifests.py defines manifest references and promotion evidence.
• direct_release.py, candidate_release.py, and manifests.py define stable lifecycle state and top-level manifests.

Foundation or hosting-provider fields must not be added to these modules merely because the first implementation needs them. Use an explicit adapter and typed extension point.

Hosting platforms and foundations

• platforms/github/ contains GitHub config, API models, refs, Releases, checks, text, lifecycle helpers, and commands.
• foundations/asf/ contains ASF-named config, dist behavior, and manifests.
• signing/openpgp.py contains the OpenPGP implementation independently of any foundation.

A future GitLab or Forgejo implementation belongs under platforms/. A future foundation policy belongs under foundations/. Core orchestration may depend on an adapter interface or typed union, but must not silently adopt one adapter’s vocabulary.

Secondary publication adapters

• publications/evidence.py dispatches adapter-owned command evidence and exposes only neutral publication and verification references to lifecycle orchestration.
• publications/pypi/ contains the PyPI config, JSON API verification, PEP 740 evidence contracts, and final-manifest revalidation.

The PyPI adapter owns distribution filename rules, PyPI JSON and Integrity API semantics, and Trusted Publisher evidence. It reuses one policy-constrained pooled download session while polling. Neither the provider-neutral lifecycle nor a hosting-platform adapter should parse those contracts. A selected PyPI target configures the exact project, service URLs, and Trusted Publisher identity; the adapter then formally selects only wheel and sdist filenames for that project and version. Cryptographic PEP 740 verification is available through the installable pypi extra.

CLI orchestration

• cli.py registers commands and normalizes arguments.
• commands/lifecycle.py resolves direct, candidate, and promotion state.
• commands/release_publication.py and commands/rc_preparation.py orchestrate bounded release steps.
• commands/vote_materials.py creates optional vote packages.
• commands/artifact_registration.py and artifact_registration/ handle typed secondary artifacts.
• command_manifests.py, manifest.py, and summary.py write machine and human outputs.

Commands should remain independently composable. They may create or revalidate one bounded unit of external state, but workflow policy and approval sequencing belong in component-owned workflows.

Verification

verification/ implements signed-source, secondary-artifact, reproducibility, inspection-bundle, and report contracts. Artifact-kind implementations are split between artifact_registration/kinds/ and verification/secondary/; reproduction diagnosis lives under verification/inspection/.

Provider-specific release verification remains with its adapter. Generic manifest and promotion evidence remains in the core.

Harness

src/buildish_release_tooling/harness/ is a test-only workflow simulator. It runs synthetic scenarios or checked-in GitHub workflows through act, using local shims and inspectable workspace state for external mutations. It is validation evidence for workflow shape and command composition, not a production release backend and not proof of GitHub Environment settings.

Placement rules

• Put deterministic identity and lifecycle rules in core/.
• Put GitHub, GitLab, Forgejo, or another host’s protocol and data under platforms/<provider>/.
• Put ASF or another foundation’s policy-specific fields and operations under foundations/<foundation>/ with explicit type names and discriminator values.
• Put package indexes, registries, and other secondary publication protocols under publications/<provider>/; expose their results through provider-neutral references.
• Put credentials in runtime integration, never authored config values.
• Add CLI flags in cli.py and bounded orchestration in the relevant commands/ module.
• Update schemas, public contract docs, and tests together when a supported file contract changes.