Release steps say to remove path deps

[Darksonn]

We used to remove path dependencies in the Cargo.toml when releasing a crate. This was to ensure that the released crate does not depend on unreleased changes in other crates, as removing the path dependency makes CI compile it using the crates.io version of the dependency.

However, we've stopped doing this, and the big reason is that it doesn't work anymore. CI triggers errors such as this one when you try it:

error: There are multiple `tokio` packages in your project, and the specification `tokio` is ambiguous.
Please re-run this command with `-p <spec>` where `<spec>` is one of the following:
  file:///home/runner/work/tokio/tokio/tokio#1.49.0
  https://github.com/rust-lang/crates.io-index#tokio@1.49.0
Error: Process completed with exit code 101.

We should either fix CI so that we can continue doing it, or we should remove this instruction from the docs.

[ADD-SP]

Cargo only looks at the patch settings in the Cargo.toml manifest at the root of the workspace. Patch settings defined in dependencies will be ignored.

https://doc.rust-lang.org/cargo/reference/overriding-dependencies.html#the-patch-section

We could try to patch the tokio-* crates in the root Cargo.toml for daily development, and remove it before the release.

[patch.crates-io]
tokio = { path = "tokio" }
tokio-macros = { path = "tokio-macros" }
tokio-test = { path = "tokio-test" }
tokio-stream = { path = "tokio-stream" }
tokio-util = { path = "tokio-util" }

[Darksonn]

I'm not sure that would work:

• If there are two crates that both depend on unreleased changes, then removing the path dep to release one may break the other.
• When we do remove the patch entries, I think that still results in the same ambiguity error as we get today.

[martin-g]

or we should remove this instruction from the docs.

Where is the document explaining the release steps ?

[ADD-SP]

After removing this release step, how to capture the issue caused by depending on unreleased crate?

[Darksonn]

Where is the document explaining the release steps ?

It's in the Cargo.toml files. E.g.:

tokio/tokio/Cargo.toml

Lines 3 to 9 in 41d1877

	# When releasing to crates.io:
	# - Remove path dependencies
	# - Update doc url
	# - README.md
	# - Update CHANGELOG.md.
	# - Create "v1.x.y" git tag.
	version = "1.49.0"

[Darksonn]

After removing this release step, how to capture the issue caused by depending on unreleased crate?

Right now we simply do not have any mechanism to catch such mistakes.

[mattiapitossi]

If I got this correctly, when we remove the path from a package (let’s say tokio-util) we create an ambiguity since tokio package has version 1.49.0 and tokio-util points to 1.44.0 pulled from crates.io.

I tried to reproduce this locally and I see the minrust step is failing with:

| error: There are multiple `tokio` packages in your project, and the specification `tokio` is ambiguous

because of

 - uses: Swatinem/rust-cache@v2
      - name: "cargo check"
        run: |
          if [[ "${{ github.event.pull_request.base.ref }}" =~ ^tokio-1\..* ]]; then
            # Only check `tokio` crate as the PR is backporting to an earlier tokio release.

            cargo check -p tokio features $TOKIO_STABLE_FEATURES
          else

Technically, to remove this ambiguity we could use --manifest-path instead of -p to specify that we want the local version. This seems to fix the issue with minrust.

There’s another problem on the docs step because by removing the path we depend on old tokio versions that does not have docs:

error: unresolved link to `tokio::select`

  --> tokio-util/src/io/simplex.rs:91:24

   |

91 | /// [`tokio::select!`](macro@tokio::select) statement and some other branch

   |                        ^^^^^^^^^^^^^^^^^^^ no item named `select` in module `tokio`

   |

   = note: `-D rustdoc::broken-intra-doc-links` implied by `-D warnings`

   = help: to override `-D warnings` add `#[allow(rustdoc::broken_intra_doc_links)]`

Maybe a solution could be to use url links instead of cross link ref? Or maybe bump some dependencies?

I’ve opened a PR for this, let me know if that make sense for you or if I’m missing something.