Release and Versioning

Bijux Proteomics is a coordinated package family. A release is therefore more than a collection of distributions: it is a claim that package metadata, compatibility boundaries, scientific evidence, and published artifacts describe the same repository state.

One Version, Several Publication Channels

The version is resolved from Git tags through hatch-vcs. Release tags use the v<version> form, and each publishable package records its user-visible changes in its own CHANGELOG.md. The tag identifies one source state; the package changelog explains the behavior and compatibility changes at that distribution boundary.

flowchart LR
    tag["release intent<br/>v&lt;version&gt;"]
    source["one source revision"]
    proof["repository and package proof"]
    artifacts["wheel, sdist, release bundle"]
    channels["PyPI, GHCR, GitHub Release"]

    tag --> source --> proof --> artifacts --> channels
    proof -. failure .-> stop["publication stops"]

The four release workflows have distinct ownership:

Workflow	Responsibility
release-artifacts.yml	Build and stage package distributions and GitHub release assets.
release-pypi.yml	Resolve the package matrix, wait for the tagged revision's CI result, and publish Python distributions.
release-ghcr.yml	Publish release bundles to the container registry.
release-github.yml	Assemble the release body and attach the staged assets to a GitHub Release.

These are parallel delivery channels for one release identity, not independent definitions of the version.

flowchart TD
    candidate["identified release candidate"] --> stage["staged immutable artifacts"]
    stage --> pypi["PyPI publication"]
    stage --> ghcr["GHCR publication"]
    stage --> github["GitHub Release"]
    stage --> docs["documentation publication"]
    pypi --> verify["consumer-side verification ledger"]
    ghcr --> verify
    github --> verify
    docs --> verify
    verify --> complete{"all intended channels coherent?"}
    complete -->|yes| released["release recorded complete"]
    complete -->|no| stop["stop promotion; retain partial publication state"]

The shared staged artifact identity prevents each channel from rebuilding its own interpretation of the tag. A partial publication is a visible release state, not permission to rebuild or retag silently.

Release Identity Contract

Before building, verify that:

• the intended v<version> tag resolves to the exact source revision under review;
• every publishable distribution resolves the same coordinated version;
• no unresolved 0.0.0, unintended prerelease, or local-version marker remains;
• every affected package has an accurate CHANGELOG.md entry;
• compatibility distributions describe the canonical owner and migration impact;
• the release matrix contains every intended PyPI, GHCR, and GitHub artifact.

The resolved version must match the version embedded in every wheel and source distribution filename and metadata record. A coherent version number does not erase independent package compatibility obligations.

Evidence Before Publication

Run repository proof before creating a release tag:

make release-preflight
make check
make build

release-preflight evaluates documentation clarity, package boundaries, test collection, benchmark assets, runtime reproducibility, consequence coherence, and artifact hygiene in a deterministic order. make check supplies the wider repository verification surface. make build creates package wheels and source distributions under artifacts/<package>/build/ and checks their metadata with Twine.

A successful build is necessary but not sufficient. Review the changelog for every affected package, the resolved version, the compatibility impact, and the scientific claim boundary. Changes to tracked API contracts, compatibility bridges, runtime migration posture, or benchmark-backed public claims require explicit release notes even when the code change appears mechanically small.

Publication Boundary

The repository root exposes build and preflight targets, but no publish target. Uploads belong to the hosted release workflows, where environment protection, trusted publishing or release credentials, tagged-commit status, and staged artifact identity can be evaluated together. Use make build for local artifact inspection; do not turn a local shell into an undocumented publication path.

bijux-proteomics-dev provides reusable version-resolution and publication guard modules. They reject unresolved versions, prerelease or local-version markers unless deliberately enabled, and distributions whose embedded version differs from the resolved source version. A release integration that uses these helpers must invoke their canonical module paths and retain Twine validation; the existence of a helper does not prove that a particular workflow calls it.

After publication, verify the artifacts from the consumer side: install from the target index into a clean environment, import the documented public packages, and exercise the smallest representative workflow. The release is complete only when the published artifact—not the source checkout—passes that check.

Record the published filenames, checksums, target channels, source revision, and clean-environment verification result. If one channel publishes a different artifact identity, stop promotion until the release set is coherent.

Partial Publication And Supersession

Published artifacts may be immutable even when another channel fails. The release record must therefore distinguish staged, published, verified, failed, and intentionally omitted channels. Recovery must reuse the reviewed artifact when the channel permits it; rebuilding creates a new artifact identity and requires renewed distribution review.

Do not delete release history or reuse a version to conceal a defective artifact. If a published distribution cannot be repaired under its immutable identity, issue a governed successor release, link the superseded release, and state the affected package, channel, consumer risk, and migration or upgrade route.

Channel evidence	Completion condition
PyPI	exact wheel/sdist hashes published; clean install, imports, metadata, and representative workflow pass
GHCR	image digest, provenance, SBOM, startup, and representative command verified from the registry
GitHub Release	tag, release body, staged assets, checksums, and source archive relationship agree
documentation	deployed revision, navigation, examples, limitations, and package/version references match the release candidate

Repository completion requires every intended channel to reach its declared condition or be recorded as withheld. One successful channel cannot stand in for the others.

Compatibility Is Part of the Release

Version movement does not make an incompatible change safe. The release record must identify the affected owner, describe the migration path, and preserve the current limits documented in Current Capability Limits. If evidence supports only a bounded workflow claim, the changelog and release body must keep that boundary intact.