Release

How to release str0m and its workspace crates.

Crate dependency graph

                              str0m
                                |
       +------+-----------+-----+-----+------------+----------+
       |      |           |           |            |          |
       v      v           v           v            v          v
      is   aws-lc-rs  rust-crypto  openssl   apple-crypto  wincrypto
       |      |           |           |            |          |
       +------+-----------+-----+-----+------------+----------+
                                |
                                v
                           str0m-proto

str0m-netem is dev-only — not pulled by published str0m.

Bumping rules

• str0m-proto: bump minor (0.x.0) when dimpl workspace dep crosses a 0.x boundary, since proto re-exports dimpl types (DtlsCert, KeyingMaterial, SrtpProfile, etc.). Patch is fine for internal-only changes.
• Crypto crates (str0m-aws-lc-rs, str0m-rust-crypto, str0m-openssl, str0m-apple-crypto, str0m-wincrypto): bump minor when dimpl crosses a 0.x boundary or when their dep on str0m-proto crosses a 0.x boundary.
• is: bump minor when its dep on str0m-proto crosses a 0.x boundary. Patch for additive API or bug fixes that don't touch the public proto-derived surface.
• str0m: minor bump per release that includes any breaking change or new public API.

The trap: don't publish leaf crates ahead of a shared-dep bump

If a release will bump str0m-proto (or dimpl such that proto must bump), do not publish is or any crypto crate against the old proto first. They'll get pinned to the old ^0.x proto on the registry, and the next time you publish str0m it will pull two proto versions into the dep tree — types like TcpType won't unify and verification fails:

expected `str0m_proto::net::TcpType`, found `TcpType`

The only fix is another minor bump of the prematurely-published crate. We hit this in 0.19.0 — is had to go 0.8.0 → 0.8.1 → 0.9.0 in one release cycle.

Rule: decide up front whether str0m-proto is bumping in this release. If yes, bump it (and everything that depends on it) in a single batch.

Release procedure

1. Decide bumps for each crate (see rules above). Update versions in:
   • Cargo.toml (root [package] and [workspace.dependencies])
   • Each sub-crate's Cargo.toml
2. Move # Unreleased in CHANGELOG.md to # <new-version>.
3. cargo check --workspace to refresh Cargo.lock and confirm it builds.
4. Commit with message <version> (e.g. 0.19.0), tag, push:

   git tag 0.19.0
   git push && git push --tags

5. Publish bottom-up. Each step waits for the previous to land on the index:

   cargo publish -p str0m-proto
   cargo publish -p is
   cargo publish -p str0m-aws-lc-rs
   cargo publish -p str0m-rust-crypto
   cargo publish -p str0m-openssl
   cargo publish -p str0m-apple-crypto
   cargo publish -p str0m-wincrypto --no-verify
   cargo publish -p str0m

6. Skip any line whose version is already on crates.io (e.g. mid-release recovery).

Notes on individual crates

• str0m-wincrypto — verify step pulls the windows crate, which fails to build on macOS due to upstream issues. Use --no-verify. CI on Windows is the real verification.
• str0m-netem — dev-only. Bump and republish only if its source changes; not required for a str0m release.
• is — independent tags are allowed (is-0.x.y), but read "the trap" above before publishing one out of band.

Verifying state on crates.io

for c in str0m str0m-proto is str0m-aws-lc-rs str0m-rust-crypto \
         str0m-openssl str0m-apple-crypto str0m-wincrypto; do
  echo -n "$c: "
  curl -s "https://crates.io/api/v1/crates/$c" \
    | python3 -c "import sys,json; print(json.load(sys.stdin)['crate']['max_version'])"
done