Consider not changing the version in `Cargo.toml` before the release is cut

[thomaseizinger]

In order to depend on unreleased versions of libraries, cargo offers a way to patch a certain version of a dependency via the [patch.crates-io].

This however only works if the version mentioned in the project Cargo.toml file is the same one as the one set in the dependency's manifest.

I am currently depending on bdk 0.14 and trying to patch bdk across my dependency graph to latest HEAD. Unfortunately, that doesn't work:

❯ cargo t
    Updating git repository `https://github.com/bitcoindevkit/bdk`
warning: Patch `bdk v0.14.1-dev (https://github.com/bitcoindevkit/bdk#64e88f0e)` was not used
in the crate graph.
Check that the patched package version and available features are compatible
with the dependency requirements. If the patch has a different version from
what is locked in the Cargo.lock file, run `cargo update` to use the new
version. This may also occur with an optional dependency that is not enabled.

Do people use the [patch.crates-io] feature? If yes, how are you dealing with pre-release version bumps in the manifest file?

[notmandatory]

If you just need to use the latest pre-released version then the patch method is a good way to go. But to use it you also need to specify the current version in the repo master branch, this will work:

[patch.crates-io]
bdk = { git = 'https://github.com/bitcoindevkit/bdk' }

[dependencies]
bdk = { version = "0.14.1-dev", default-features = false, features = ["all-keys"]}

[thomaseizinger]

This doesn't quite work unfortunately.

The point of [patch] is to replace dependencies across the entire dependency graph without changing the [dependencies] table. In my case, bdk is also a transitive dependency and I cannot change the version referenced in that dependency's manifest file (without forking / changing it).

So to apply your suggestion, I need to:

1. Fork / change said dependency to a bdk version that does not exist yet (0.14.1-dev)
2. Push that change
3. [patch] that dependency in my application
4. Change the bdk version in my application
5. [patch] bdk in my application

At that point, I might as well not use [patch] and modify the [dependencies] table of both crates to point to a specific revision :man_shrugging:

[LLFourn]

This however only works if the version mentioned in the project Cargo.toml file is the same one as the one set in the dependency's manifest.

I don't have to be the same it just has to be compatible right? I would have expected 0.14.1-dev to be compatible with 0.14 in the dependency's Cargo.toml. Then cargo should use it after cargo update.

To me it looks like patch is just not behaving correctly here. See this post where the user does the same thing https://github.com/rust-lang/cargo/issues/2222#issuecomment-590616041 This should work. I think patch's behaviour is wrong.

[thomaseizinger]

I would have expected 0.14.1-dev to be compatible with 0.14 in the dependency's Cargo.toml. Then cargo should use it after cargo update.

From the spec:

A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version.

I think this says that 0.14.1-dev might not necessarily yield a 0.14.1 and is thus not safe to automatically upgrade from 0.14.0 like 0.14.1 would be.

[LLFourn]

I think you're right. I would expect patch to somehow relax this rule or provide a way of more powerfully overriding.

[thomaseizinger]

Yes, I've longed for a more "brutal" [patch] behaviour myself several times but it is unfortunately fairly restrictive :/

[notmandatory]

In chat with @LLFourn sounds like this will also be of use to his projects. I propose:

1. After we create a new release/0.x.0 branch we bump the version in the master branch to release/0.x+1.0. This lets someone [patch] to the next unreleased MINOR version.
2. After we cargo release version 0.x.0 from the release/0.x.0 branch, we then bump the to version in that branch to 0.x.1. This lets you [patch] bdk to a possible next PATCH version.

[LLFourn]

I think this works @thomaseizinger? if so I guess this can be closed.

[notmandatory]

With changed proposed in #544 you should be able to use pre-release versions by pointing your [patch] to either the release/0.x or master branch and version.