Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Releasing

All canton-* crates release in lockstep on one version (ADR-0005). Publishing is the one step here that cannot be undone — a crates.io version is permanent, and half a family published in the wrong order leaves the rest unpublishable until the next version.

Order

cargo publish builds the package to verify it, which resolves dev dependencies as well as normal ones, so a crate cannot go before anything it depends on either way. This order is derived from the manifests, not from memory:

  1. canton-core
  2. canton-lf
  3. canton-proto
  4. canton-auth
  5. canton-codegen
  6. canton-signer
  7. canton-admin
  8. canton-codegen-cli
  9. canton-daml
  10. canton-daml-stdlib
  11. canton-ledger
  12. canton-splice-api-featured-app-v1
  13. canton-splice-api-token-metadata-v1
  14. canton-splice-api-token-holding-v1
  15. canton-splice-api-token-holding-v2
  16. canton-splice-api-token-allocation-v1
  17. canton-splice-api-token-allocation-v2
  18. canton-splice-api-token-burn-mint-v1
  19. canton-splice-api-token-transfer-events-v2
  20. canton-splice-api-token-transfer-instruction-v1
  21. canton-splice-api-token-transfer-instruction-v2
  22. canton-splice-api-token-allocation-instruction-v1
  23. canton-splice-api-token-allocation-instruction-v2
  24. canton-splice-api-token-allocation-request-v1
  25. canton-splice-api-token-allocation-request-v2
  26. canton-splice-amulet
  27. canton-token
  28. canton-pqs
  29. canton-splice-wallet-payments
  30. canton
  31. canton-splice-wallet

Re-derive the order after adding a crate:

cargo metadata --format-version 1 --no-deps >/dev/null   # manifests parse
tools/publish-order.sh                                    # prints the list above

Each step waits for the index: cargo publish -p <crate> then let it appear before the next (crates.io is usually seconds; cargo publish will fail fast with “no matching package” if it is not there yet).

Before publishing

  • cargo fmt --all --check
  • cargo clippy --workspace --all-targets --all-features -- -D warnings
  • cargo test --workspace --all-features
  • RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --all-features
  • cargo deny check all
  • cargo hack clippy --workspace --feature-powerset --no-dev-deps -- -D warnings
  • cargo semver-checks over every crate with a published baseline — the list CI’s semver job carries in .github/workflows/ci.yml (eleven at 0.2.x). A crate joins that list in the release after it first publishes; the M3 crates (canton-signer, canton-pqs, canton-token, canton-daml-stdlib, the canton-splice-api-* set) join at the release after 0.3.0. (only crates with a published baseline; add each new one after its first release)
  • The live suites against a participant, with skips made fatal: CANTON_TEST_REQUIRE_LIVE=1 cargo test -p canton-ledger --features ws --test live and the same for -p canton-admin
  • The reference app end to end on both transports: cargo run -p canton-sample
  • CHANGELOG.md: turn — unreleased into the date
  • README.md: every place that names a version — the status line, the compatibility table, and any “unreleased”/“this branch” wording. The README is frozen into each published crate’s page at publish time, so a stale line there is not fixable until the next release: grep -nE "unreleased|this branch|0\.[0-9]+\.[0-9]+" README.md
  • book/src, the docs site’s own pages: every place that names a version, such as the --version in the codegen guide’s cargo install lines: git grep -nE "0\.[0-9]+\.[0-9]+" -- book/src (reference/ and project/ there are generated from the files above and not tracked)
  • The tree is clean and tagged v<version>

After publishing

The pre-publish cargo package runs with --no-verify, and it has to: verifying builds the packaged crate, which needs its siblings at the new version to exist on crates.io, and they do not yet. So the packaged artefact is first built by whoever installs it. Do that yourself, from a directory outside this workspace so nothing resolves by path:

cargo new /tmp/consumer && cd /tmp/consumer
cargo add canton --features ws,otel,pqs-tls
cargo add canton-daml canton-splice-amulet canton-token canton-pqs canton-signer
cargo build            # the family, as a user gets it

cargo install canton-codegen-cli --root /tmp/tools
/tmp/tools/bin/dpm-codegen-rust --dar <any>.dar --out /tmp/bindings
cd /tmp/bindings && cargo build   # generated code against the published runtime

Then check every crate documented, not just built — https://docs.rs/crate/<name>/<version>/status.json reports doc_status. A crate can publish and install perfectly while its documentation page says the build failed, and that cannot be fixed without another release.

  • GitHub release on the tag, notes from the changelog section
  • docs/compatibility-matrix.md (M3 onward) names the released version