RELEASE.md

Versioning strategy

For public-api and cargo-public-api we bump

• x.0.0
  • no earlier than rustdoc JSON format stabilization.
• 0.x.0
  • independently between public-api and cargo-public-api. ¹
  • when public_api::MINIMUM_NIGHTLY_RUST_VERSION is bumped. ²
  • when public-api changes how items are rendered. ³
  • for other regular semver breaking changes. ⁴
• 0.0.x
  • whenever we want to make a release but don't have to/want to bump 0.x.0.

When not to release

• If a package had no x.0.0 or 0.x.0 updates to regular dependencies (we disregard dev-dependencies) we don't need a new release of that package. ⁵

How to release

cargo-public-api

1. Make sure you have done cargo install cargo-edit to make cargo set-version available.
2. First release rustup-toolchain, rustdoc-json and public-api if needed, in that order. See below.
3. Create a local branch.
4. Run

   tag=$(git tag --sort=-creatordate | grep ^v | head -n1) ; git diff $tag
   

   to see what is new in the release.
5. Update CHANGELOG.md
6. Bump version with

   cargo set-version -p cargo-public-api x.y.z
   

   If 0.x.0 or public_api::MINIMUM_NIGHTLY_RUST_VERSION was bumped:
   • Add a new version info entry at version_info.rs
   • Run cargo run --bin update-version-info
7. Push branch

MAINTAINER:

1. Once PR merges, run https://github.com/cargo-public-api/cargo-public-api/actions/workflows/Release-cargo-public-api.yml workflow from main (instructions)
2. Done!

public-api

1. Run

   tag=$(git tag --sort=-creatordate | grep ^public-api-v | head -n1) ; git diff $tag -- public-api/
   

   to see if a release is needed.
2. If changes detected, create a local branch.
3. Update public-api/CHANGELOG.md
4. Bump version with

   cargo set-version -p public-api x.y.z
   

   If 0.x.0 or public_api::MINIMUM_NIGHTLY_RUST_VERSION was bumped:
   • Update version_info.rs
   • Run cargo run --bin update-version-info
5. Push branch

MAINTAINER:

1. Once PR merges, run https://github.com/cargo-public-api/cargo-public-api/actions/workflows/Release-public-api.yml workflow from main (instructions)
2. Done!

rustdoc-json

1. Run

   tag=$(git tag --sort=-creatordate | grep ^rustdoc-json-v | head -n1) ; git diff $tag -- rustdoc-json/
   

   to see if a release is needed.
2. If changes detected, create a local branch.
3. Update rustdoc-json/CHANGELOG.md
4. Bump version with

   cargo set-version -p rustdoc-json x.y.z
   

5. Push branch

MAINTAINER:

1. Once PR merges, run https://github.com/cargo-public-api/cargo-public-api/actions/workflows/Release-rustdoc-json.yml workflow from main (instructions)
2. Done!

rustup-toolchain

1. Run

   tag=$(git tag --sort=-creatordate | grep ^rustup-toolchain-v | head -n1) ; git diff $tag -- rustup-toolchain/
   

   to see if a release is needed.
2. If changes detected, create a local branch.
3. Update rustup-toolchain/CHANGELOG.md
4. Bump version with

   cargo set-version -p rustup-toolchain x.y.z
   

5. Push branch

MAINTAINER:

1. Once PR merges, run https://github.com/cargo-public-api/cargo-public-api/actions/workflows/Release-rustup-toolchain.yml workflow from main (instructions)
2. Done!

How to trigger main branch workflow

1. Go to https://github.com/cargo-public-api/cargo-public-api/actions and select workflow in the left column
2. Click the Run workflow ▼ button to the right
3. Make sure the main branch is selected
4. Click Run workflow
5. Wait for the workflow to complete

Footnotes

1. But if public_api::MINIMUM_NIGHTLY_RUST_VERSION has been bumped then public-api and cargo-public-api by necessity must bump to the same 0.x.0 version for the compatibility matrix. ↩

2. Since we need to be able to add a new row to the compatibility matrix. ↩

3. Because otherwise CI checks would fail from 0.0.x updates. ↩

4. E.g. changes to the public-api public API or the cargo-public-api CLI. ↩

5. Because there are no technical reasons to do it. On the contrary, it creates unnecessary churn for downstream users. ↩