RELEASE.md~5 min readRelease & Version Control Process
This document defines the official Semantic Versioning, trunk-based branching, automated build/attestation pipeline, and user self-update lifecycle for mimikyu.
1. Versioning Policy (SemVer 2.0.0)
mimikyu follows Semantic Versioning 2.0.0 (MAJOR.MINOR.PATCH) synchronized across the Cargo workspace:
Cargo.toml([workspace.package].version) is the single source of truth inherited by bothcrates/mimikyu-coreandcrates/mimikyu-cli.Cargo.lock,packaging/homebrew/mimikyu.rb, andCHANGELOG.mdare kept strictly synchronized and verified in CI by./scripts/check-version-sync.sh.- Pre-
1.0(0.y.z) rules:0.MINOR.0— New features, new MCP tools, CLI flag additions, or intentional minor contract evolutions documented inCHANGELOG.md.0.y.PATCH— Backwards-compatible bug fixes, driver protocol resilience improvements, security fixes, and performance optimizations.
1.0.0+rules:MAJOR— Breaking CLI--jsonenvelope changes, removed CLI flags/subcommands, breaking MCP tool input schemas, or publicmimikyu-coreAPI breaks.MINOR— Backwards-compatible CLI/MCP/library additions.PATCH— Backwards-compatible bug and security fixes.
2. Trunk-Based Branching & PR Flow
flowchart LR
A["Feature / Fix Branch"] --> B["Pull Request to main"]
B --> C["ci.yml + security.yml Gates"]
C --> D["Squash Merge to main"]
D --> E["./scripts/release.sh X.Y.Z"]
E --> F["Push Tag vX.Y.Z"]
F --> G["release.yml: Build + SHA256SUMS + SLSA Attest"]
G --> H["GitHub Release + install.sh --update"]
mainis always releasable: All development happens on short-lived topic branches (feat/<topic>,fix/<topic>,docs/<topic>,chore/<topic>) targetingmain.- Conventional Commits & Changelog:
- PR titles and squash-merge commits use Conventional Commits (
feat:,fix:,perf:,docs:,test:,chore:). - User-visible additions, fixes, or security changes add an entry under
## [Unreleased]in CHANGELOG.md.
- PR titles and squash-merge commits use Conventional Commits (
- Automated PR Gates:
.github/workflows/ci.yml: Version sync, POSIX shell lint, path/secret hygiene,cargo clippy --workspace --all-targets -- -D warnings, workspace unit & integration tests (Linux + macOS), Python E2E--self-test+ Chromium/Firefox E2E suites, andinstall.sh --from-sourcesmoke tests..github/workflows/security.yml:cargo-denylicense/source/ban checks andcargo-auditRustSec vulnerability scanning.
3. Cutting a Production Release (scripts/release.sh)
Never manually edit version numbers across scattered files or push unverified tags. Always use ./scripts/release.sh from a clean main checkout.
Step 1: Sync main & Run Local Pre-Flight Checks
git checkout main
git pull --ff-only origin main
# Verify workspace lints, unit/integration tests, and version sync
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
python3 e2e/run_e2e.py --self-test
./scripts/check-version-sync.sh
Step 2: Review CHANGELOG.md & Run a Dry-Run Simulation
Confirm ## [Unreleased] in CHANGELOG.md summarizes all changes since the previous tag, then preview the release without modifying the working tree:
./scripts/release.sh --dry-run 0.1.1
--dry-run stages the manifest, lockfile, Homebrew formula, and changelog updates in a temporary directory, runs ./scripts/check-version-sync.sh --tag v0.1.1 against the simulated files, and prints every planned command while leaving your working tree untouched.
Step 3: Cut the Release Commit & Annotated Tag
# Creates commit `chore(release): v0.1.1` and annotated tag `v0.1.1` locally
# Pass `--sign` to force GPG/SSH tag signing (`git tag -s`)
./scripts/release.sh 0.1.1
What ./scripts/release.sh executes deterministically:
- Confirms the current branch is
main, the git working tree is clean, and tagvX.Y.Zdoes not already exist. - Updates
[workspace.package] version = "X.Y.Z"inCargo.tomlandversion "X.Y.Z"inpackaging/homebrew/mimikyu.rb. - Runs
cargo check --workspacesoCargo.lockupdates cleanly. - Stamps
CHANGELOG.md(## [Unreleased]followed by## [X.Y.Z] - YYYY-MM-DD). - Verifies full consistency via
./scripts/check-version-sync.sh --tag vX.Y.Z. - Commits
chore(release): vX.Y.Zand creates annotated git tagvX.Y.Z.
Step 4: Inspect & Push to Trigger Production release.yml
By default, ./scripts/release.sh never pushes automatically so maintainers can inspect the commit and tag first:
git show v0.1.1
git push origin main
git push origin v0.1.1
(Alternatively, pass --push directly: ./scripts/release.sh --sign --push 0.1.1.)
4. Automated Production Pipeline (.github/workflows/release.yml)
Pushing a v*.*.* tag triggers .github/workflows/release.yml across three gated stages:
verifyGate:- Executes
./scripts/check-version-sync.sh --tag ${{ github.ref_name }}(blocking publication if tag,Cargo.toml,Cargo.lock, Homebrew formula, orCHANGELOG.mdare out of sync). - Runs
cargo clippy --workspace --all-targets -- -D warnings,cargo test --workspace --locked, andpython3 e2e/run_e2e.py --self-test.
- Executes
buildMatrix:- Compiles
--release --lockedmimikyubinaries and packagesmimikyu-<target>.tar.gzarchives for:aarch64-apple-darwin(macOS Apple Silicon)x86_64-apple-darwin(macOS Intel)x86_64-unknown-linux-gnu(Linux x86_64)aarch64-unknown-linux-gnu(Linux ARM64)
- Compiles
publish& Provenance Attestation:- Computes
SHA256SUMSacross all 4 tarballs. - Renders a release-ready
mimikyu.rbHomebrew formula populated with${{ github.repository }}, the release version, and the exact SHA-256 digests. - Signs SLSA build provenance for
mimikyu-*.tar.gzandSHA256SUMSusingactions/attest-build-provenance@v2. - Extracts the stamped
## [X.Y.Z]release notes fromCHANGELOG.mdand publishes the GitHub Release (automatically marking-alpha,-beta, or-rctags as pre-releases).
- Computes
5. User Installation, Verification & Update Lifecycle
Once release.yml publishes vX.Y.Z, users upgrade safely across supported channels:
POSIX CLI Self-Updater (install.sh)
# Atomically upgrade if a newer GitHub Release tag is available
curl -fsSL https://raw.githubusercontent.com/YXZYSME/mimikyu/main/install.sh | sh -s -- --update
# Pin a specific version and verify both SHA-256 + GitHub SLSA Artifact Attestation
curl -fsSL https://raw.githubusercontent.com/YXZYSME/mimikyu/main/install.sh | \
sh -s -- --version v0.1.1 --verify-attestation
Security guarantees enforced by install.sh:
- Downloads both
mimikyu-<target>.tar.gzandSHA256SUMSinto a private temporary directory (mktemp -d). - Verifies the 64-character SHA-256 digest before extracting (
shasum -a 256/sha256sum), aborting immediately on any mismatch. - Optionally verifies cryptographic SLSA provenance via
gh attestation verify --repo YXZYSME/mimikyuwhen--verify-attestationis passed. - Stages the binary in the destination directory and swaps it into place via atomic POSIX
mv.
Homebrew Tap (packaging/homebrew/mimikyu.rb)
Copy the rendered mimikyu.rb asset attached to the GitHub Release into Formula/mimikyu.rb in your homebrew-tap repository (YXZYSME/homebrew-tap), allowing users to run:
brew update && brew upgrade mimikyu
Cargo & cargo-binstall
# Prebuilt binary via [package.metadata.binstall]
cargo binstall mimikyu-cli
# Build from tagged git source
cargo install --locked --git https://github.com/YXZYSME/mimikyu --tag v0.1.1 mimikyu-cli
6. Hotfixes & Failed Release Recovery
- If
release.ymlfails before publishing a GitHub Release: Fix the issue via a normal PR tomainand cut the next patch version (X.Y.(Z+1)). Avoid deleting and force-repushing publicvX.Y.Ztags once pushed, as downstream caches and checksum verifiers treat release tags as immutable. - If a critical regression or vulnerability is discovered in
vX.Y.Z:- Mark the affected GitHub Release as pre-release or add an advisory banner pointing to the patch version (never silently overwrite release tarballs).
- Land the fix on
mainand immediately cutvX.Y.(Z+1)via./scripts/release.shsoinstall.sh --updateupgrades users atomically.