Release Support¶
Bijux Canon resolves one tag-derived release line into independently built
Python distributions and specialized PyPI, GHCR, and GitHub Release paths.
bijux-canon-dev owns version resolution and publication eligibility; build
logic owns wheel and source-distribution construction; workflows own registry
credentials and publication timing.
flowchart LR
source[Tagged source] --> version[Resolve version]
version --> guard[Publication guard]
guard --> build[Build wheel and sdist]
build --> metadata[Twine and package checks]
metadata --> stage[Stage release artifacts]
stage --> pypi[PyPI]
stage --> ghcr[GHCR]
stage --> github[GitHub Release]
Version Resolution¶
release.version_resolver evaluates sources in order:
- a static
[project].version, when declared; python -m hatch versionin the package directory;- the latest Git tag matching the package’s Hatch tag pattern or package tag convention;
0.0.0when none resolves.
The repository packages normally use Hatch VCS and the shared v<version> tag
pattern. A dirty or untagged checkout can resolve to a development or local
version suitable for testing but not normal publication.
Publication Guard¶
release.publication_guard rejects:
- prerelease identifiers unless
--allow-prereleaseis explicit; - local or dirty version identifiers unless
--allow-local-versionis explicit; - a distribution directory with no recognized wheel or source distribution;
- artifact filenames whose parsed version differs from the resolved version.
The Make integration separately refuses unresolved 0.0.0 and requires at
least one wheel and one source distribution. Exceptions permit an intentional
prerelease or local publication; they do not change the version embedded in
built files. The guard parses both wheel and .tar.gz filenames and reports
every mismatch.
flowchart TD
resolved[Resolved version] --> known{Not 0.0.0?}
known -- no --> refuse[Refuse publication]
known -- yes --> policy{Prerelease/local allowed?}
policy -- no --> refuse
policy -- yes --> files{Wheel and sdist exist?}
files -- no --> refuse
files -- yes --> match{Artifact versions match?}
match -- no --> refuse
match -- yes --> twine[Twine metadata validation]
Build Evidence¶
The shared build path creates both wheel and source distribution beneath the
configured package artifact directory and runs twine check unless explicitly
disabled. Repository contract tests additionally verify that public packages:
- include package source, README, and changelog in the source distribution;
- include typing metadata in the wheel;
- force-include the repository license;
- link package legal files to the root authority;
- keep package-local build products ignored;
- preserve compatibility-package build boundaries.
Package profiles may add release-specific checks before or after the common
build. Inspect the selected package’s release-dry behavior rather than
assuming all distributions have identical evidence.
Wheel Family Verification¶
The installed bijux-canon-wheel-inventory command validates the exact
workspace wheel and source-archive family against checked-in metadata. The repository
workspace currently declares twelve distributions; the non-publishable root
project is not a thirteenth release artifact.
It compares names, one shared version, Python constraints, dependencies,
optional extras, console entry points, and license declarations. It also
verifies archive paths, wheel tags, every RECORD hash and byte count, exact
copies of LICENSE and NOTICE, declared runtime assets such as py.typed and
schema hashes, and the absence of source-tree, test, cache, and local path
leaks. Each distribution must also have exactly one safe, same-version source
archive with matching PKG-INFO and a packaged pyproject.toml. A real
twine check over every wheel and source archive is part of the result.
bijux-canon-wheel-inventory \
--repo-root . \
--wheel-dir artifacts/release/wheels \
--output artifacts/release/wheel-inventory.json
The command requires a clean checkout and writes the Twine command outcome,
wheel and source-archive hashes, source metadata hashes, lock hash, environment identity, package
results, and retained failures to the requested JSON file. The wheel directory,
cache, and result must remain under artifacts/; the validator and its tests
remain in bijux-canon-dev so the same release contract survives disposal of a
particular run's evidence.
Clean Installation Verification¶
The installed bijux-canon-installation-matrix command creates a clean
environment for every wheel and one additional environment for the complete
exact family. Candidate constraints bind any sibling distribution selected by
dependency resolution to the same wheel version. A separate sealed dependency
installation directory supplies third-party wheels; it is built from the
lock-exported acquisition cache before the matrix runs. Every install forces
--no-index and rejects candidate distributions duplicated in that directory.
Each row runs the package manager consistency check, imports modules with
Python isolation enabled, loads all installed entry points, resolves declared
runtime data from site-packages, and invokes each console command's help
surface. Imports or data that resolve into the repository source tree fail the
row.
bijux-canon-installation-matrix \
--repo-root . \
--wheel-dir artifacts/release/wheels \
--dependency-wheel-dir artifacts/release/dependency-install-wheels \
--environment-root artifacts/release/installations \
--output artifacts/release/install-matrix.json
The result retains every environment-creation, installation, consistency, inspection, and command outcome. Cross-platform and cross-Python coverage is composed with the supported Python matrix; one local installation run does not imply those remote runner results.
Advertised Extras Verification¶
The installed bijux-canon-extras-matrix command installs and exercises every
advertised extra in isolation. It uses the same sealed dependency wheelhouse as
the clean installation matrix, disables public-index access, verifies imported
capabilities resolve from the isolated environment, and retains dependency
wheel hashes with every command outcome.
bijux-canon-extras-matrix \
--repo-root . \
--wheel-dir artifacts/release/wheels \
--dependency-wheel-dir artifacts/release/dependency-install-wheels \
--environment-root artifacts/release/extras \
--output artifacts/release/extras-matrix.json
Supported Python Verification¶
The installed bijux-canon-python-support command treats package metadata as
the support authority. It refuses classifier drift between packages, a
requires-python contradiction, missing or duplicate wheels, mixed package
versions, malformed wheel metadata, unsafe archive paths, an incomplete
canonical/compatibility partition, or a missing platform promise. It then
installs the exact repository-and-package wheel family under every advertised
Python minor, runs the package-manager consistency check, imports every shipped
module from the isolated site-packages, and loads every console entry point.
The result carries a distinct status for all 48 package and interpreter
combinations.
bijux-canon-python-support \
--repo-root . \
--wheel-dir artifacts/release/wheels \
--environment-root artifacts/release/python-support/environments \
--output artifacts/release/python-support/result.json
The command requires a clean checkout so the recorded full source commit names
the exact tested tree. Wheel inputs, environments, caches, command logs, and the
JSON result must stay under artifacts/; they are run evidence, not product
source. The local result records its platform explicitly. Multi-platform
enforcement remains a remote-runner responsibility and must not be inferred
from a single local pass.
Release Identity Preflight¶
The installed bijux-canon-release-candidate command binds a proposed stable
tag to the clean source commit, lockfile, all twelve same-version wheels,
fallback versions, and candidate changelog headings. Its live preflight also
requires an unused remote Git tag, no published or draft GitHub Release, an
unused exact PyPI version for all twelve distribution names, and no matching
tag on the eleven GHCR packages selected by the public-release inventory.
Authenticated repository push permission is required because GitHub exposes
draft releases only to suitably authorized callers. Registry failures are
indeterminate failures, not evidence that a name is available.
bijux-canon-release-candidate \
--repo-root . \
--wheel-dir artifacts/release/wheels \
--output artifacts/release/release-candidate.json \
--tag v0.4.0 \
--github-repository bijux/bijux-canon \
--remote origin
The result records the timestamp and exact read-only queries. Refresh it immediately before approval because registry availability can change after a successful run. The command never creates a tag, release, or registry object.
Local Publication Is Safe by Default¶
The shared publish target checks the version, builds artifacts, and validates
them. Upload is disabled unless PUBLISH_UPLOAD_ENABLED=1. publish-test
similarly requires its explicit enable flag. Registry upload refuses missing
credentials.
SKIP_TWINE_CHECK=1, prerelease allowance, local-version allowance, and
SKIP_EXISTING=1 are visible policy choices. --skip-existing avoids failing
on a version already present; it cannot replace immutable registry bytes and
must not be used to imply that the local build is identical to the published
artifact.
TestPyPI installation verification exists only when a package configures
PUBLISH_VERIFY_INSTALL_CMD. An unconfigured target reports that it did not
run; it is not an installation pass.
Workflow Separation¶
| Workflow | Authority |
|---|---|
release-artifacts.yml |
build and stage package distributions and optional SBOM assets |
release-pypi.yml |
publish staged Python distributions |
release-ghcr.yml |
publish OCI release bundles to GHCR |
release-github.yml |
create or update GitHub Release assets |
Staging and publication remain separate so artifact contents can be reviewed before credentials are used. A successful artifact build does not prove PyPI publication, and a successful registry upload does not prove that GitHub Release or SBOM staging completed.
Release Acceptance Record¶
Retain:
- source tag, commit SHA, clean/dirty state, and resolved version;
- selected public package and compatibility-package inventory;
- wheel and source-distribution filenames and registry identities;
- publication-guard and Twine results;
- package-specific release-dry evidence;
- production and development SBOMs plus validation results;
- workflow run IDs and destination-specific publication results;
- changelog and compatibility decisions for caller-visible changes.
Published bytes are immutable. Recovery from an incorrect release uses a new source decision and version, with yanking or deprecation where supported; it does not rebuild and overwrite the existing version.
Failure Routing¶
| Failure | Owning boundary |
|---|---|
version is 0.0.0 or dirty |
version resolver, tag, or checkout state |
| artifact version mismatch | build environment or stale artifact directory |
| Twine metadata refusal | package metadata or build contents |
| missing wheel or sdist | build target and staged artifact path |
| missing PyPI credential | publication workflow or local secret injection |
| package absent from matrix | root public release inventory and workflow inputs |
| compatibility artifact points to wrong owner | compatibility package metadata and contract tests |
| SBOM absent | SBOM generation, validation, or release staging |
See SBOM and Supply Chain for inventory evidence, the root Release and Versioning guide for package-family policy, and Release Workflows for workflow orchestration.