84 lines
2.8 KiB
Markdown
84 lines
2.8 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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.
|