dbtool-cli-v1/RELEASE_RUNBOOK.md

dbtool-cli-v1 Release Runbook

Purpose

This runbook defines the smallest release artifact contract for dbtool-cli-v1.

Current Baseline

• Release smoke is implemented in .github/workflows/release-smoke.yml.
• The workflow targets Linux, macOS, and Windows release runners.
• Each runner builds the release binary, runs --help and --version, packages one distributable archive, and emits a SHA256 checksum.
• Local validation in the current backend environment is limited to the Linux packaging path; macOS and Windows still require GitHub-hosted runners or equivalent CI workers.

Artifact Contract

• Linux: dbtool-<version>-x86_64-unknown-linux-gnu.tar.gz
• macOS: dbtool-<version>-x86_64-apple-darwin.tar.gz
• Windows: dbtool-<version>-x86_64-pc-windows-msvc.zip
• Checksum: <artifact-name>.sha256

Each packaged artifact contains:

• dbtool or dbtool.exe
• README.md
• RELEASE_RUNBOOK.md
• SMOKE_RUNBOOK.md

CI Steps

Each matrix entry in .github/workflows/release-smoke.yml performs:

1. install stable Rust
2. cargo build --release --bin dbtool
3. smoke the binary with --help and --version
4. package one archive with the platform naming contract
5. generate a SHA256 sidecar file
6. upload the archive and checksum as workflow artifacts

Local Linux Validation

In a Linux environment with the same linker workaround used by the repo:

export HOME="$AGENT_HOME"
export CARGO_HOME="$AGENT_HOME/.cargo"
export RUSTUP_HOME="$AGENT_HOME/.rustup"
export PATH="$CARGO_HOME/bin:$PATH"
export CC="$AGENT_HOME/tools/zig-cc"
export AR="$AGENT_HOME/tools/zig-ar"
export CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER="$AGENT_HOME/tools/zig-cc"

cargo build --release --bin dbtool
scripts/release/smoke-binary.sh target/release/dbtool
scripts/release/package-unix.sh x86_64-unknown-linux-gnu target/release/dbtool

Expected outputs:

• dist/dbtool-<version>-x86_64-unknown-linux-gnu.tar.gz
• dist/dbtool-<version>-x86_64-unknown-linux-gnu.tar.gz.sha256

QA Usage

For a produced artifact, QA should:

1. verify the SHA256 checksum
2. unpack the archive
3. run dbtool --help
4. run dbtool --version
5. follow SMOKE_RUNBOOK.md for database-backed validation in a Docker-capable environment

Rollback

If a newly built artifact fails smoke or QA validation:

1. stop distributing the new archive set
2. keep the failing archive and checksum for investigation
3. redirect consumers back to the most recent previously verified artifact set
4. record the failure cause, affected platform, and whether the issue is build-time, package-time, or runtime

Current Blocker

This runbook cannot claim fully verified cross-platform release readiness until the workflow runs successfully on real Linux, macOS, and Windows runners and QA completes the Docker-backed smoke path.