Document that package can be used in [patch]

[alexcrichton]

This works to [patch] multiple versions of a crate, and turns out this
has worked since the inception of package!

Closes #6169

[rust-highfive]

r? @ehuss

(rust_highfive has picked a reviewer for you, use r? to override)

[ehuss]

Heh, I stumbled on an issue (#7264).

I'm thinking it might be helpful to add a note expanding on this a little, since I don't think it is obvious how this works. I think there are two points to make:

• When using the package key, the aliased name on the left doesn't really matter. It is not used to correlate with actual dependency names.
• Each entry should point to a source with a different version in its Cargo.toml.

(Not sure how to say these two things succinctly and clearly.)

The second point is complex. I would like to at some point add an entire chapter on how version resolution works. When we do that, we can maybe include a dedicated sub-section on how [patch] affects things. For now, I think a brief sentence is fine, we can link it later.

Some of the complexities I'm thinking of are:

• The two patches should have versions that are semver-incompatible. (This is not entirely correct, it only really applies to caret requirements. It's hard to express in a simple way.)
• You can't selectively change a semver-incompatible version requirement. That is, you can't patch a dependency of "^0.9" to something that defines "1.0.0".
• If the patched version is older than what is available, it won't match if it is not already locked. That is, if you patch to a source that defines "1.0.1", but crates.io has "1.0.2", and you don't have a Cargo.lock then the patch won't work. But it will work if Cargo.lock is locked to 1.0.1.

[Hoverbear]

Rest LGTM. Great digging @alexcrichton !

[alexcrichton]

@Hoverbear I think you're running into #5478, although it may be manifesting as a panic. I suspect if the panic is fixed then it still won't work due to #5478.

@ehuss excellent points! I think you're definitely right in that we're about 4 years late for having a section on how the resolver works in the documentation. I'll think on this and see if I can figure out a better set of words to include.

[Hoverbear]

@alexcrichton Ha! Seems this leads down the rabbit hole to #6921 and #5471 :-P

[alexcrichton]

Ok I've touched up some wording and such and spawned off #7301 for more comprehensive documentation about how [patch] and the resolver interact. @ehuss want to take another look?

[alexcrichton]

Er I messed up git and didn't actually push, pushed now.

[ehuss]

@bors r+

[bors]

📌 Commit 2a391a7 has been approved by ehuss

[bors]

⌛ Testing commit 2a391a7 with merge 5947fb8...

[bors]

☀️ Test successful - checks-azure
Approved by: ehuss
Pushing 5947fb8 to master...