Maintainer Release Runbook

Maintainer Release Runbook

This runbook is for maintainers preparing and publishing releases.

If you are in a hurry, do not skip Section 2 (local checks) and Section 3 (tag/release gating).

Source-of-truth automation lives in the repository workflows. Treat this runbook as operational guidance that should stay aligned with CI.

Before You Tag

• Ensure branch is clean and synced.
• Ensure release version metadata is aligned (pyproject.toml, README/security messaging).
• Ensure generated kit bundles are current after kit source changes.
• Confirm changelog/release notes scope.

Run Local Checks

Run full checks before tagging:

uv run ruff check src tests
uv run ruff format --check src tests
uv run mypy src
uv run pytest tests/unit -v
uv run pytest tests/integration -v
uv run pytest tests/e2e -v

Coverage gate (current CI-equivalent):

uv run pytest tests/unit tests/integration --cov=ethernity --cov-report=term-missing --cov-fail-under=85

Kit verification:

cd kit
npm ci
npm test
node build_kit.mjs
cd ..

Tag and Release Gating

Release tags are expected in vX.Y.Z form.

Release prechecks should block publishing unless:

• tag resolves correctly
• tag version matches project version at the tagged commit
• latest CI run for target SHA is successful

Manual checks here complement CI gates; they do not replace them.

Validate Artifacts

Expected release matrix:

• linux x64
• linux arm64
• macOS x64
• macOS arm64
• windows x64

Each variant should include archive + provenance sidecars (SBOM and Sigstore bundle). See Release Artifacts for operator-facing verification commands.

Common Failure Modes

CI green locally but release gate blocked

• Check workflow precheck logs for latest-run status and tag/version mismatch.

kit-verify fails with "bundles are out of date"

• Rebuild kit bundles and commit generated outputs:
  • src/ethernity/resources/kit/recovery_kit.bundle.html
  • src/ethernity/resources/kit/recovery_kit.scanner.bundle.html

Windows-only unit test failures

• Confirm tests do not assert POSIX-only path strings.
• Normalize expected path assertions using platform-native Path string rendering.

Coverage gate suddenly drops

• Re-run the exact CI command locally.
• Confirm test selection still matches current CI workflow.

After Release

• Verify release page contains all expected artifacts.
• Spot-check verification command examples against one variant.
• Verify Homebrew tap/bottle workflow completed if this release should update Homebrew.
• Announce any policy-impacting changes (trust model, format, or operational behavior).

Related

• Release Artifacts
• Homebrew Packaging
• Troubleshooting
• Command Cheatsheet