diff --git a/docs/contributing/how-to-specify-crates-dependencies-versions.md b/docs/contributing/how-to-specify-crates-dependencies-versions.md index 97220a7bd..5f08a6840 100644 --- a/docs/contributing/how-to-specify-crates-dependencies-versions.md +++ b/docs/contributing/how-to-specify-crates-dependencies-versions.md @@ -1,7 +1,7 @@ # How to specify crates dependencies versions Each crate (e.g., `tokio-util`, `tokio-stream`, etc.) should specify dependencies -according to these rules: +according to the following rules: 1. The listed version should be the oldest version that the crate works with (e.g., if `tokio-util` works with `tokio` version `1.44` but not `1.43`, then @@ -10,7 +10,7 @@ We don't require users to use the latest version unnecessarily. 2. When a crate starts using a newer feature in a dependency, the version should be bumped to the version that introduced it. 3. If a crate depends on an unreleased feature in a dependency, it may use -`path = ` dependency to specify this. Since path dependencies must be removed +`path =` dependency to specify this. Since path dependencies must be removed during the release of the crate, this ensures that it can't be released until the dependency has a new version. @@ -20,12 +20,13 @@ Consider the following example from `tokio-stream`: [dependencies] futures-core = { version = "0.3.0" } pin-project-lite = "0.2.11" -tokio = { path = "../tokio", features = ["sync"] } +tokio = { version = "1.38.0", path = "../tokio", features = ["sync"] } ``` In this case, local development of `tokio-stream` uses the local version of `tokio` via the `path` dependency. This means that it's currently not -possible to release `tokio-stream`. Once a new version of `tokio` is -released, the path dependency will be removed from `tokio-stream`. +possible to release `tokio-stream`, and `tokio` should be released first. +Once a new version of `tokio` is released (in this example the `1.38.0`), +the path dependency should be removed. As mentioned before, this version should only be bumped when adding a new feature in the crate that relies on a newer version.