0.x-beta-release-checklist.md

0.x Beta Release Checklist

Use this checklist before tagging a public beta. Leave a box open until the result is verified for the exact release source and its evidence is retained. Candidate-specific scope and limitations belong in its release notes. Published versions and artifacts are listed on GitHub Releases.

The current source and packaging version is set in Cargo.toml (scripts/sync-versions.sh mirrors it everywhere). Until the annotated tag and release artifacts are published, the tree is a release candidate. Keep every box open until dated, provenance-complete evidence satisfies it.

Build and quality

Verify the repository from a fresh clone, without the private planning workspace or an OASIS source tree:

• cargo fmt --all -- --check is clean
• cargo check --workspace --all-targets --locked is clean
• cargo test --workspace --locked passes, including local shape and real-backend-driver completeness checks
• scripts/release-dry-run.sh produces the expected artifacts
• The exact source commit, test suite, test data, and results are recorded

Provider comparisons

• cargo fmt --all -- --check clean
• cargo check --workspace --all-targets --locked clean
• cargo test --workspace --locked green, including local shape and real-backend-driver completeness checks
• scripts/release-dry-run.sh produces the expected artifacts
• Verified from a fresh clone of this repository alone (not via the planning workspace)
• Intended check commit and clean framework/test-data provenance recorded

Parity evidence

The nightly workflow is a code/CI gate; it does not replace this source-bound direct-versus-proxied release evidence.

See parity-validation.md. For each of SoftHSM2, NSS softokn, Kryoptic:

• Full suite run direct and proxied
• Dated direct, proxied, and comparison artifacts retain complete provenance
• Explicit 30-provider non-mock matrix completed and retained with provenance
• Outcome classes compared; mismatches triaged (provider-specific / proxy bug / known issue). Provider-conformance fixes stay out of proxy scope: proxy bugs fixed here, provider issues reported upstream and recorded, never normalized by the proxy (see the parity triage rules)
• No open release-blocking proxy bug
• Residual differences recorded in the support matrix

Documentation

• README beta-scope matches the support matrix
• mtls-setup.md reflects the real config fields and the private-key permission requirement
• Operator runbook current
• error-reference current
• Documentation distinguishes released behavior from unreleased changes
• ADRs reflect public released behavior and mark local unreleased increments accurately (incl. ADR-0006 32-bit-deferred, ADR-0007 crash isolation)

Support-claim discipline

• Support matrix claims only what the evidence supports
• Plain TCP without mTLS still documented as not a public claim (unless an explicit decision has changed that)
• No "production-ready" or broad-vendor language anywhere public
• LICENSE(s) present; crate metadata (version, license, and ideally repository/description) set for the release

Freeze and publish

• Version bumped via scripts/sync-versions.sh X.Y.Z (workspace version, crate pins, packaging mirrors, README token, lockfiles); scripts/sync-versions.sh --check and the packaging smoke pass

• Release notes state the scope, validated providers, and limitations

• Code and documentation are frozen in one subject commit; the quality receipt names its full SHA

• The matching versioned quality receipt names that subject and records exactly pass for fmt, check, test, clippy, msrv, audit, deny, and release_dry_run

• A final bookkeeping commit changes only CHANGELOG.md and the quality receipt; the changelog contains a dated heading for the intended version

• The bookkeeping commit passes:

  ```bash
  export TAG=vX.Y.Z
  scripts/verify-release-subject.sh "$TAG"
  scripts/test-verify-quality-receipt.sh
  GITHUB_REF_NAME="$TAG" scripts/release-dry-run.sh
  ```
  

• The exact tag was created and pushed by the maintainer (the dispatcher is the sole authorizer; no approvals):

  ```bash
  git tag -a "$TAG" -m "pkcs11-proxy-ng $TAG"
  git push origin "$TAG"
  ```
  

• The published release contains the Linux archive, Windows ZIP, inventory.json, and assets.json; the compare-then-stage gate verified the staged set

crates.io publication and registry-source binaries

See the publication guide for the machinery; record the run here.

• Staging account/endpoint/token (crates-io-staging) exists before dispatch
• Either the orchestrator path (cut-release.yml dispatched from the GUI with version/mode/package; verify green, publish auto-dispatched) or the manual path below was followed; partial states recovered by hand as guided
• Staging probe published from main first; ordinary dry-runs stayed upload-free
• publish.yml dispatched from the exact tag with the intended mode (dry-run, bootstrap, or trusted) and package selection; bootstrap used only until one trust record per crate exists
• Full CI, artifact smokes, all-eight checksum verification, and registry consumers green; complete=true emitted before any binary build started
• Partial publication, if any, recovered by individual-member dispatch; the follow-up command from the run was used
• Release assets compared before publication: identical retained, missing added, none divergent; no tag moved, replaced, or deleted
• Pre-auth candidate, post-upload evidence, and release assets retained (90-day run artifacts) and escrowed to maintainer long-term storage with the location recorded in the release notes
• docs.rs builds confirmed for all eight crates after publication