mirror of https://github.com/fluencelabs/rust-libp2p synced 2025-05-16 04:41:20 +00:00

docs(release): Skip unused cargo release steps

`cargo release` provides multiple steps:
- changes
- version
- replace
- hook
- commit
- publish
- owner
- tag
- push
- config
- help

We only make use of `publish` and `tag`. We explicitly don't want `cargo release` to do `version` or `commit`.

Update the release docs accordingly, namely replace the generic `cargo release` with a two step process `cargo release publish` and `cargo release tag`.

Pull-Request: #3596.

2023-03-14 19:22:21 +00:00

2.7 KiB

Raw Blame History

Release process

This project follows semantic versioning. The following documentation will refer to X.Y.Z as major, minor and patch version.

Development between releases

Every substantial pull request should add an entry to the [unreleased] section of the corresponding crate CHANGELOG.md file. See #1698 as an example.

In case there is no [unreleased] section yet, create one with an increased major, minor or patch version depending on your change. Update the version in the crate's Cargo.toml. In addition update the corresponding entry of the crate in the root level Cargo.toml and add an entry in the root level CHANGELOG.md.

Releasing one or more crates

Prerequisites

cargo release

Steps

Remove the [unreleased] tag for each crate to be released in the respective CHANGELOG.md. Create a pull request with the changes against the rust-libp2p master branch.
Once merged, run the two commands below on the (squash-) merged commit on the master branch.
1. cargo release publish --execute
2. cargo release tag --sign-tag --execute
Confirm that cargo release tagged the commit correctly via git push $YOUR_ORIGIN --tag --dry-run and then push the new tags via git push $YOUR_ORIGIN --tag. Make sure not to push unrelated git tags.

Note that dropping the --no-push flag on cargo release might as well do the trick.

Patch release

Create a branch v0.XX off of the minor release tag.
Merge patches into branch in accordance with development between releases section.
Cut release in accordance with releasing one or more crates section replacing master with v0.XX.

Dealing with alphas

Unfortunately, cargo has a rather uninutitive behaviour when it comes to dealing with pre-releases like 0.1.0-alpha. See this internals thread for some context: https://internals.rust-lang.org/t/changing-cargo-semver-compatibility-for-pre-releases

In short, cargo will automatically update from 0.1.0-alpha.1 to 0.1.0-alpha.2 UNLESS you pin the version directly with =0.1.0-alpha.1. However, from a semver perspective, changes between pre-releases can be breaking.

To avoid accidential breaking changes for our users, we employ the following convention for alpha releases:

For a breaking change in a crate with an alpha release, bump the "minor" version but retain the "alpha" tag. Example: 0.1.0-alpha to 0.2.0-alpha.
For a non-breaking change in a crate with an alpha release, bump or append number to the "alpha" tag. Example: 0.1.0-alpha to 0.1.0-alpha.1.

2.7 KiB Raw Blame History