Skip to content

Commit

Permalink
Document new policy on breaking changes and changelog entries
Browse files Browse the repository at this point in the history
  • Loading branch information
thomaseizinger committed Mar 15, 2023
1 parent 91d63f7 commit 3b5da29
Showing 1 changed file with 24 additions and 11 deletions.
35 changes: 24 additions & 11 deletions docs/release.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,29 @@ 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](https://github.com/libp2p/rust-libp2p/pull/1698/files) as an example.
### Prefer non-breaking changes

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`.
We strive to minimize breaking changes for our users.
PRs with breaking changes are not merged immediately but collected in a milestone.
For example: https://github.com/libp2p/rust-libp2p/milestone/6.

Non-breaking changes are typically merged very quickly and often released as patch-releases soon after.

### Make changelog entries

Every crate that we publish on `crates.io` has a `CHANGELOG.md` file.
Substantial PRs should add an entry to each crate they modify.
The next unreleased version is tagged with ` - unreleased`, for example: `0.17.0 - unreleased`.

In case there isn't a version if an ` - unreleased` postfix yet, add one for the next version.
The version number depends on the impact of your change (breaking vs non-breaking, see above).

If you are making a non-breaking change, please also bump the version number in the `Cargo.toml` manifest.
In case another crate _depends_ on the new features or APIs that you are adding, you may need to bump the dependency declaration in that `Cargo.toml` file as well.
Don't worry if you don't get this one right, we will flag it in the PR if necessary :)

For breaking changes, a changelog entry itself is sufficient.
Bumping the version in the `Cargo.toml` file itself as well leads to merge conflicts once we decide to merge them.

## Releasing one or more crates

Expand All @@ -23,9 +37,8 @@ documentation will refer to `X.Y.Z` as _major_, _minor_ and _patch_ version.

### Steps

1. 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.
1. 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.

2. Once merged, run the two commands below on the (squash-) merged commit on the `master` branch.

Expand Down

0 comments on commit 3b5da29

Please sign in to comment.