Skip to content

Maintainers release runbook

How to cut a multi-channel release. Contributors: see CONTRIBUTING.md.

Pre-flight

  1. Update versions together:
  2. Cargo.toml / workspace versions
  3. pyproject.toml
  4. Binding manifests if versioned independently
  5. Docs that hard-code 0.x.y (getting-started expected output, migration pins)
  6. Update CHANGELOG.md (move Unreleased → version section)
  7. Sync conformance manifests:
  8. src/conformance/manifest.json
  9. tests/conformance/manifest.json
  10. Local gates:
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test --locked
cargo test --test phase_0_10 --locked
cargo test --test phase_0_11 --locked
cargo test --test portable_relational --locked
cargo run --bin dtcs -- conformance run --profile all
pytest python/tests -v
NO_MKDOCS_2_WARNING=true ./scripts/check-docs.sh

  1. Changelog → docs checklist (when behavior or versions change):

  2. [ ] versioning.md / getting-started expected dtcs version output

  3. [ ] cli-guide.md command table + new flags
  4. [ ] api/python.md / api/rust.md / WASM/Node
  5. [ ] json-output.md envelope examples (specVersion, new commands)
  6. [ ] troubleshooting.md diagnostic remediation table
  7. [ ] Migration guides / FAQ if upgrade story changes

  8. [ ] MkDocs nav + hub tables in docs/README.md

  9. Binding smokes (from repo):

cd bindings/wasm && npm test
cd ../node && npm test

Tag and publish

git tag v0.x.y
git push origin v0.x.y

.github/workflows/release.yml publishes crates.io / PyPI when secrets are configured. npm publish runs only when NPM_TOKEN is set.

Verify

  • crates.io / PyPI show 0.x.y
  • pip install dtcs==0.x.y && dtcs version
  • docs.rs builds for the tag
  • Read the Docs picks up main / tags as configured
  • Optional: npm view @eddiethedean/dtcs version when npm publish is enabled

Failure modes

Symptom Check
PyPI missing wheel maturin/release job logs; Python version matrix
crates.io reject version already published; cargo publish --dry-run
npm skipped NPM_TOKEN unset (expected)
Conformance drift dual manifest sync; phase_0_10 / phase_0_11 / portable_relational tests