Skip to content

Release Checklist

Step-by-step guide for tagging a new Silvasonic release.

0. Release Type & Quality Gates

Every version bump must be classified as one of two types. The quality gates differ accordingly.

Feature Release (Minor or Major: X.Y.0)

Adds new functionality, changes behavior, or introduces new services. All of the following are mandatory before tagging:

  • [ ] Changed-Path Test Audit — Every new or modified code path has been explicitly reviewed and mapped to the appropriate verification tier (Unit for isolated logic, Integration for DB/Redis/service contracts, System for lifecycle/hardware). If no direct test is added, the reason must be stated explicitly.
  • [ ] No New Test Anti-Patterns in Changed Scope — Tests added or modified for this release have been reviewed against testing.md. Mock-heavy verification, call-chain mirroring, and coverage-driven bloat were not introduced in the changed scope. Existing legacy anti-patterns outside the release scope were documented but do not require unrelated refactoring before release.
  • [ ] Critical Path Verification — All new or changed state transitions, database queries, failure recovery paths, and hardware interactions are explicitly guarded by appropriate tests. Boilerplate or framework glue may remain indirectly tested only if it has no meaningful standalone contract and the relevant behavior is covered at a higher tier.
  • [ ] Smoke Tests — Every service included in the release has a passing smoke test (@pytest.mark.smoke)
  • [ ] just check-all passes — Full CI pipeline (lint, type-check, all test tiers, container build, compose validation) runs cleanly
  • [ ] Hardware Tests (recommended) — If USB microphone hardware is available, run just test-hw (@pytest.mark.system_hw). These tests validate real device detection, profile matching, and container spawning with physical hardware. Not mandatory, but strongly recommended before any release that touches device detection or Recorder spawning.

[!CAUTION] A Feature Release MUST NOT be tagged if any of the above gates fails. Fix all issues first, then re-run just check-all until clean.

Patch Release (Bug-Fix / Stabilization: X.Y.Z where Z > 0)

Bug fixes only. Pre-v1.0.0, internal behavior changes or architecture refactorings that enforce system stability and core directives (like data integrity) without introducing new user-facing features are permitted to maintain a clean baseline.

  • [ ] just check-all passes
  • [ ] Regression test for the fixed bug (recommended, ideally mandatory)

1. Set Version

Silvasonic has one central version file. All sub-packages (Controller, Recorder) derive their version dynamically via Hatch.

File Update? Description
packages/core/src/silvasonic/core/__init__.py YES — Single Source of Truth __version__ = "X.Y.Z"
pyproject.toml (Root) YES version = "X.Y.Z"
ROADMAP.md Line 3 YES > **Status:** vX.Y.Z — Milestone
README.md Line 5 YES > **Status:** vX.Y.Z — Milestone
ROADMAP.md Milestone table YES Set version status to ✅ Current, mark previous as ✅ Done
Sub-package pyproject.toml NO Version is derived dynamically from silvasonic-core

2. Run All Checks

All checks must pass before tagging:

just check-all

This includes:

  • Ruff — Linting & Formatting
  • Mypy — Type Checking
  • pytest — Unit, Integration, System & Smoke Tests
  • pip-audit — Dependency Security Audit
  • uv lock --check — Lock File Consistency
  • Containerfile Lint — Hadolint + Compose YAML Validation

[!TIP] If you have a USB microphone connected, also run just test-hw to validate hardware detection, profile matching, and Recorder spawning with real devices. This is strongly recommended but not enforced by just check-all.

If any check fails: Fix → Commit → Re-run just check-all.

3. Commit & Tag

Final Commit

Ensure all changes are committed:

git status                # No uncommitted changes
git add -A
git commit -m "release: vX.Y.Z — Milestone-Name"

Create Annotated Tag

git tag -a vX.Y.Z -m "vX.Y.Z — Milestone-Name"

Important: Always use annotated tags (-a), never lightweight tags. Annotated tags include author, date, and message.

Push (Including Tag)

git push origin main
git push origin vX.Y.Z

4. Post-Release

  • [ ] ROADMAP.md: Mark next version as 🔨 In Progress
  • [ ] Optionally create a GitHub Release (recommended from v1.0.0 onwards with CHANGELOG)