Release Process

DotMatch releases should be specific, reproducible, and evidence-bounded.

Pre-Tag Checks

Run the consolidated local pre-tag gate:

make pretag-ready

It is a local readiness gate and intentionally does not include make distribution-channels, make workflow-adoption-status, or make bcl-comparison-gate. Those gates require public/external evidence and are listed below.

The target runs:

make test
make cli-test
make asan
make python-test
make python-package-test
make docs-ready
make repository-ready
make release-ready
make scientific-readiness-ready
make assay-evidence-ready
make alphabet-policy-ready
make citation-metadata-ready
make native-comparator-scope-ready
make distribution-record-ready
make bioconda-recipe-ready
make coverage
make native-exact-gate
make public-crispr-evidence-gate
make crispr-comparison-gate
make barcode-comparison-gate
make feature-barcode-public-gate
make perturb-seq-public-gate
make amplicon-panel-public-gate
make bcl-tiny-public-gate
make oligo-adapter-public-gate
make workflow-examples-ready
npm run lint
npm audit --audit-level=moderate
npm run build
NEXT_OUTPUT=export NEXT_PUBLIC_BASE_PATH=/dotmatch NEXT_PUBLIC_SITE_URL=https://dnncha.github.io/dotmatch npm run build

make bcl-comparison-gate requires additional real-data and comparator evidence. Keep release notes within the evidence that is checked into the repository.

Tagging

Use annotated tags:

git tag -a v<version> -m "DotMatch v<version>"
git push origin v<version>

Pushing v* tags runs .github/workflows/release.yml. The workflow starts with a preflight job that runs make test, make cli-test, make asan, make python-test, installs the public docs toolchain, make repository-ready, make release-ready, and make python-package-test; artifact publication jobs depend on that preflight. The workflow builds:

  • raw Linux wheel release artifact;

  • macOS wheel;

  • source distribution;

  • repaired manylinux/musllinux Linux wheels for PyPI;

  • GHCR container image;

  • SHA256SUMS.txt;

  • PyPI publication through trusted publishing for the sdist, macOS wheel, and repaired Linux wheels;

  • a draft GitHub release with generated notes.

Keep the GitHub release as a draft until the release notes, artifacts, checksums, CITATION.cff, and codemeta.json have been checked.

Release Notes

Lead with:

  • exact known-target short-DNA assignment;

  • deterministic unique, ambiguous, none, and invalid semantics;

  • CRISPR guide-counting, exact-prefix inline-barcode, narrow feature-barcode assignment, narrow CRISPR guide-capture assignment, and narrow ARTIC amplicon primer-start assignment evidence only where gates pass;

  • package/install improvements;

  • clear scope boundaries.

Avoid:

  • genome-aligner language;

  • universal guide-counter replacement language;

  • broad barcode, feature quantification, amplicon consensus/variant-calling, or BCL comparisons without matching evidence.

Distribution Follow-Up

  • Confirm the Zenodo archive for the tagged release and add the release DOI to CITATION.cff when available.

  • Publish the PyPI source distribution, native macOS wheel, and repaired manylinux/musllinux wheels through trusted publishing; do not upload raw linux_x86_64 wheels. The PyPI project must have a trusted publisher matching repository dnncha/dotmatch, workflow .github/workflows/release.yml, and environment pypi.

  • For Bioconda updates, submit or update the bioconda-recipes recipe after make bioconda-recipe-ready. Keep the osx-arm64 additional-platforms opt-in in that recipe copy so Bioconda CI validates the Apple Silicon build. Replace the source SHA256 only in the upstream recipe copy. After merge and channel propagation, verify with make distribution-channels before announcing conda install instructions or BioContainers availability.

  • Confirm the GHCR image labels and tag after the source tag is immutable.

  • Run make distribution-channels after PyPI, Bioconda, GHCR, and Zenodo are public.

  • Update docs/distribution-release.json with verified public and evidence links after public channels are live.

  • Update docs/scientific-claims.md only when new evidence is committed and a corresponding gate passes.