Merge branch 'master' into 2680-explore

Author: thomaseizinger

.github/mergify.yml

@@ -13,8 +13,12 @@ pull_request_rules:
   - name: Ask to resolve conflict
     conditions:
       - conflict
-      - -draft # Draft PRs are allowed to have conflicts.
       - -author=dependabot[bot]
+      - or:
+        - -draft # Don't report conflicts on regular draft.
+        - and: # Do report conflicts on draft that are scheduled for the next major release.
+          - draft
+          - milestone~=v[0-9]\.[0-9]{2}
     actions:
       comment:
         message: This pull request has merge conflicts. Could you please resolve them @{{author}}? 🙏

docs/release.md

@@ -5,15 +5,30 @@ 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 with an ` - unreleased` postfix yet, add one for the next version.
+The next 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 would lead to many merge conflicts once we decide to merge them.
+Hence, we are going to bump those versions once we work through the milestone that collects the breaking changes.
 
 ## Releasing one or more crates
 
@@ -23,9 +38,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.