Releasing in Linebender projects

Several Linebender packages are published to crates.io. When we do so, we follow a process to ensure that:

For backports, see the Backports in Linebender Projects post

Before the release

Preparing for a release

We should make sure that the changelog accurately reflects all important changes since the previous release. It's especially important that we capture all breaking changes. This happens as a normal PR, following normal processes. We want to have any updates to the changelog content happen before the release PR itself (see Preparing the release). This is primarily because changelog content updates are more likely to run into merge conflicts.

Dependencies

We make sure that all dependencies are at their latest version. This is achieved by running:

# Updates dependencies in Cargo.toml files.
cargo upgrade --ignore-rust-version
# Updates Cargo.lock to match what new users who add our crate will use.
# This ensures our testing is realistic.
cargo update --ignore-rust-version

You should also check that the cargo upgrade output doesn't list any breaking releases of our dependencies. Note that we have a public dependency on some crates (especially wgpu), which we want to keep synchronised across our projects.

This will be submitted as a PR, following normal processes.

See rfcs#5 for motivation of this strategy.

Preparing the release

Anyone can prepare the release PR (although it should be an organisation member). The PR which makes a release should only bump version numbers in Cargo.toml (and Cargo.lock) files, and update the changelog as described below.

To validate the release, you can run: cargo publish -p {crate1} -p {crate2} --dry-run. At this stage, you should only be doing a dry run. Cargo should probably not be logged into crates.io at this stage.

The updates required in the changelog are as follows:

It's recommended to run markdownlint on the resultant changelog, to ensure that all links are up-to-date. The author does this through the DavidAnson.vscode-markdownlint VSCode extension, but other ways of running it are available.

Note: Linebender uses the current date in the UTC time zone for release dates in changelogs. In the evening in America this might be the next day than the one in your calendar, and for the morning in Australia, this might be the previous day.

Releasing

Release pull requests are an exception to our "author merges" policy. Instead release PRs can only be merged by someone who has release permissions, and who will then perform the release once the PR is merged.

Checking permissions

The person who is making the release needs all of the following permissions:

Checking the dates

The release date in the changelog should be updated to the correct current date just before merging. This person performing the release should do this step, not the PR author.

Note: Linebender uses the current date in the UTC time zone. In the evening in America this might be the next day than the one in your calendar, and for the morning in Australia, this might be the previous day.

Merging the release PR

The release PR should be merged, after it has been approved. This will use our standard merge queue. The merge will be queued by the person performing the release.

Validating correct commit

Once the release PR has been merged, you should check out the main branch, and pull from it. You should also validate that the current checked out commit git rev-parse --short HEAD matches the newly created commit on main (e.g. through the GitHub web interface, using gh repo view --web).

Publishing

You are now ready to perform the publish. As a security best practice, you should only log cargo into crates.io whilst making releases. The author uses 1Password to achieve this, but alternatively making a short-lived token on crates.io as you make a release is also an acceptable way to achieve this. Note that we don't enforce this.

If you're publishing multiple crates at once, you should publish using cargo publish -p {crate1} -p {crate2}. This ensures that each of the crates will compile successfully.

For new crates, we make sure that at least three Linebender organisation members have publish permissions. This should include Raph, and at least one organisation admin. Ask on Zulip if you're unsure about this step.

GitHub release

We also create a GitHub release and git tag for each release. The easiest way to do both is through GitHub's web interface.

Once this is done, the GitHub release can be created.

Zulip message

We also share releases on the Linebender Zulip. The format for this message is:

{Crate Name} v{x.x.x} is out now:

- [GitHub Release](URL of the release on GitHub)
- [Crates.io](https://crates.io/crates/{package_name}/{x.x.x})
- [Docs](https://docs.rs/{package_name}/{x.x.x})

The format can be slightly different if the release involves multiple packages. See the message sent for the previous release for that project in this case.

We also occasionally share releases on Mastodon.

Checklist

Before Release
During Release