ci: fix ambiguity issue during tokio releases (#7848)

.cirrus.yml

@@ -25,7 +25,7 @@ task:
       rustc --version
   test_script:
     - . $HOME/.cargo/env
-    - cargo test --all --features $TOKIO_STABLE_FEATURES
+    - cargo test --workspace --features $TOKIO_STABLE_FEATURES
     # Free the disk space before the next build,
     # otherwise cirrus-ci complains about "No space left on device".
     - cargo clean
@@ -68,4 +68,4 @@ task:
       rustc --version
   test_script:
     - . $HOME/.cargo/env
-    - cargo test --all --features $TOKIO_STABLE_FEATURES --target i686-unknown-freebsd
+    - cargo test --workspace --features $TOKIO_STABLE_FEATURES --target i686-unknown-freebsd

.github/workflows/ci.yml

@@ -112,6 +112,16 @@ jobs:
         run: |
           set -euxo pipefail
           cargo nextest run --workspace --features $TOKIO_STABLE_FEATURES
+          # Removing workspace patches to run tests without path dependencies
+          # (if not specified differently in the crate)
+          sed -i.bak '/^\[patch\.crates-io\]$/d; /^tokio = { path = "tokio"\s*}$/d' Cargo.toml && rm -f Cargo.toml.bak
+          cargo nextest run \
+            --workspace \
+            --exclude tokio \
+            --exclude examples \
+            --features $TOKIO_STABLE_FEATURES
+          # Cargo nextest does not support doctest, so we run them separately
+          # (see https://github.com/nextest-rs/nextest/issues/16)
           cargo test --doc --workspace --features $TOKIO_STABLE_FEATURES
 
   test-workspace-all-features-panic-abort:
@@ -211,7 +221,13 @@ jobs:
       - uses: Swatinem/rust-cache@v2
 
       - name: Check tests --features ${{ env.TOKIO_STABLE_FEATURES }}
-        run: cargo check --workspace --tests --features $TOKIO_STABLE_FEATURES
+        run: |
+          set -euxo pipefail
+          cargo check --workspace --tests --features $TOKIO_STABLE_FEATURES
+          # Removing the tokio workspace patch to run tests without path dependencies
+          # (if not specified differently in the crate)
+          sed -i '/^\[patch\.crates-io\]$/d; /^tokio = { path = "tokio"\s*}$/d' Cargo.toml
+          cargo check --workspace --exclude tokio --tests --features $TOKIO_STABLE_FEATURES
 
   valgrind:
     name: valgrind
@@ -716,6 +732,10 @@ jobs:
         uses: dtolnay/rust-toolchain@stable
         with:
           toolchain: ${{ env.rust_min }}
+      - name: Install cargo-hack
+        uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-hack
       - uses: Swatinem/rust-cache@v2
       - name: "cargo check"
         run: |
@@ -728,7 +748,7 @@ jobs:
 
             cargo check -p tokio --features $TOKIO_STABLE_FEATURES
             # Other crates doesn't have unstable features, so we can use --all-features.
-            cargo check -p tokio-macros -p tokio-stream -p tokio-util -p tokio-test --all-features
+            cargo hack check -p tokio-macros -p tokio-stream -p tokio-util -p tokio-test --all-features
           fi
 
   minimal-versions:
@@ -797,10 +817,18 @@ jobs:
           components: clippy
       - uses: Swatinem/rust-cache@v2
       # Run clippy
-      - name: "clippy --all --features ${{ env.TOKIO_STABLE_FEATURES }}"
-        run: cargo clippy --all --tests --no-deps --features $TOKIO_STABLE_FEATURES
-      - name: "clippy --all --all-features --unstable"
-        run: cargo clippy --all --tests --no-deps --all-features
+      - name: "clippy --workspace --features ${{ env.TOKIO_STABLE_FEATURES }}"
+        run: |
+          cargo clippy --workspace --tests --no-deps --features $TOKIO_STABLE_FEATURES
+          # Removing the tokio workspace patch to check without path dependencies
+          # (if not specified differently in the crate)
+          sed -i '/^\[patch\.crates-io\]$/d; /^tokio = { path = "tokio"\s*}$/d' Cargo.toml
+          cargo clippy --workspace --exclude tokio --tests --no-deps --features $TOKIO_STABLE_FEATURES
+      - name: "clippy --workspace --all-features --unstable"
+        run: |
+          cargo clippy --workspace --tests --no-deps --all-features --config 'patch.crates-io.tokio.path="tokio"'
+          # check without path dependencies
+          cargo clippy --workspace --exclude tokio --tests --no-deps --all-features
         env:
           RUSTFLAGS: --cfg tokio_unstable -Dwarnings
 
@@ -1061,7 +1089,7 @@ jobs:
           RUSTDOCFLAGS: -C link-args=--max-memory=67108864
 
       - name: WASI test tokio-stream
-        run: cargo test -p tokio-stream --target ${{ matrix.target }} --features time,net,io-util,sync
+        run: cargo test --manifest-path=tokio-stream/Cargo.toml --target ${{ matrix.target }} --features time,net,io-util,sync
         env:
           CARGO_TARGET_WASM32_WASIP1_RUNNER: "wasmtime run --"
           CARGO_TARGET_WASM32_WASIP1_THREADS_RUNNER: "wasmtime run -W bulk-memory=y -W threads=y -W shared-memory=y -S threads=y --"

Cargo.toml

@@ -15,6 +15,9 @@ members = [
   "tests-integration",
 ]
 
+[patch.crates-io]
+tokio = { path = "tokio" }
+
 [workspace.metadata.spellcheck]
 config = "spellcheck.toml"
 

docs/contributing/README.md

@@ -37,6 +37,7 @@ If you are unsure where to begin, use the following guides:
     - [Review a bit at a time](reviewing-pull-requests.md#review-a-bit-at-a-time)
     - [Be aware of the person behind the code](reviewing-pull-requests.md#be-aware-of-the-person-behind-the-code)
     - [Abandoned or Stalled Pull Requests](reviewing-pull-requests.md#abandoned-or-stalled-pull-requests)
+- [How to specify crates dependencies versions](how-to-specify-crates-dependencies-versions.md)
 - [Keeping track of issues and PRs](keeping-track-of-issues-and-prs.md)
     - [Area](keeping-track-of-issues-and-prs.md#area)
     - [Category](keeping-track-of-issues-and-prs.md#category)

docs/contributing/how-to-specify-crates-dependencies-versions.md

@@ -0,0 +1,31 @@
+# How to specify crates dependencies versions
+
+Each crate (e.g., `tokio-util`, `tokio-stream`, etc.) should specify dependencies
+according to these 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
+`tokio-util` should specify version `1.44` for its `tokio` dependency).
+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
+during the release of the crate, this ensures that it can't be released until
+the dependency has a new version.
+
+Consider the following example from `tokio-stream`:
+
+```toml
+[dependencies]
+futures-core = { version = "0.3.0" }
+pin-project-lite = "0.2.11"
+tokio = { 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`.
+As mentioned before, this version should only be bumped when adding a new
+feature in the crate that relies on a newer version.

tokio-macros/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "tokio-macros"
 # When releasing to crates.io:
-# - Remove path dependencies
+# - Remove path dependencies (if any)
 # - Update CHANGELOG.md.
 # - Create "tokio-macros-x.y.z" git tag.
 version = "2.6.0"
@@ -27,7 +27,7 @@ quote = "1"
 syn = { version = "2.0", features = ["full"] }
 
 [dev-dependencies]
-tokio = { version = "1.0.0", path = "../tokio", features = ["full"] }
+tokio = { version = "1.0.0", features = ["full", "test-util"] }
 
 [package.metadata.docs.rs]
 all-features = true

tokio-stream/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "tokio-stream"
 # When releasing to crates.io:
-# - Remove path dependencies
+# - Remove path dependencies (if any)
 # - Update CHANGELOG.md.
 # - Create "tokio-stream-0.1.x" git tag.
 version = "0.1.18"
@@ -38,14 +38,14 @@ signal = ["tokio/signal"]
 [dependencies]
 futures-core = { version = "0.3.0" }
 pin-project-lite = "0.2.11"
-tokio = { version = "1.38.0", path = "../tokio", features = ["sync"] }
-tokio-util = { version = "0.7.0", path = "../tokio-util", optional = true }
+tokio = { version = "1.38.0", features = ["sync"] }
+tokio-util = { version = "0.7.0", optional = true }
 
 [dev-dependencies]
-tokio = { version = "1.2.0", path = "../tokio", features = ["full", "test-util"] }
+tokio = { version = "1.38.0", features = ["full", "test-util"] }
 async-stream = "0.3"
 parking_lot = "0.12.0"
-tokio-test = { version = "0.4", path = "../tokio-test" }
+tokio-test = "0.4"
 futures = { version = "0.3", default-features = false }
 
 [package.metadata.docs.rs]

tokio-test/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "tokio-test"
 # When releasing to crates.io:
-# - Remove path dependencies
+# - Remove path dependencies (if any)
 # - Update CHANGELOG.md.
 # - Create "tokio-test-0.4.x" git tag.
 version = "0.4.5"
@@ -17,12 +17,12 @@ Testing utilities for Tokio- and futures-based code
 categories = ["asynchronous", "development-tools::testing"]
 
 [dependencies]
-tokio = { version = "1.2.0", path = "../tokio", features = ["rt", "sync", "time", "test-util"] }
-tokio-stream = { version = "0.1.1", path = "../tokio-stream" }
+tokio = { version = "1.2.0", features = ["rt", "sync", "time", "test-util"] }
+tokio-stream = "0.1.1"
 futures-core = "0.3.0"
 
 [dev-dependencies]
-tokio = { version = "1.2.0", path = "../tokio", features = ["full"] }
+tokio = { version = "1.2.0", features = ["full"] }
 futures-util = "0.3.0"
 
 [package.metadata.docs.rs]

tokio-util/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "tokio-util"
 # When releasing to crates.io:
-# - Remove path dependencies
+# - Remove path dependencies (if any)
 # - Update CHANGELOG.md.
 # - Create "tokio-util-0.7.x" git tag.
 version = "0.7.18"
@@ -35,7 +35,7 @@ join-map = ["rt", "hashbrown"]
 __docs_rs = ["futures-util"]
 
 [dependencies]
-tokio = { version = "1.47.0", path = "../tokio", features = ["sync"] }
+tokio = { version = "1.47.0", features = ["sync"] }
 bytes = "1.5.0"
 futures-core = "0.3.0"
 futures-sink = "0.3.0"
@@ -47,9 +47,9 @@ tracing = { version = "0.1.29", default-features = false, features = ["std"], op
 hashbrown = { version = "0.15.0", default-features = false, optional = true }
 
 [dev-dependencies]
-tokio = { version = "1.0.0", path = "../tokio", features = ["full"] }
-tokio-test = { version = "0.4.0", path = "../tokio-test" }
-tokio-stream = { version = "0.1", path = "../tokio-stream" }
+tokio = { version = "1.0.0", features = ["full"] }
+tokio-test = "0.4.0"
+tokio-stream = "0.1"
 
 async-stream = "0.3.0"
 futures = "0.3.0"

tokio/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "tokio"
 # When releasing to crates.io:
-# - Remove path dependencies
+# - Remove path dependencies (if any)
 # - Update doc url
 #   - README.md
 # - Update CHANGELOG.md.
@@ -136,9 +136,9 @@ features = [
 ]
 
 [dev-dependencies]
-tokio-test = { version = "0.4.0", path = "../tokio-test" }
-tokio-stream = { version = "0.1", path = "../tokio-stream" }
-tokio-util = { version = "0.7", path = "../tokio-util", features = ["rt"] }
+tokio-test = "0.4.0"
+tokio-stream = "0.1"
+tokio-util = { version = "0.7", features = ["rt"] }
 futures = { version = "0.3.0", features = ["async-await"] }
 futures-test = "0.3.31"
 mockall = "0.13.0"