Document that package can be used in [patch]

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

Closes #6169

Author: alexcrichton

src/doc/src/reference/manifest.md

@@ -958,6 +958,30 @@ technical specification of this feature.
 [crates.io]: https://crates.io/
 [replace]: specifying-dependencies.md#overriding-dependencies
 
+#### Using `[patch]` with multiple versions
+
+You can patch in multiple versions of the same crate with the `package` key used
+to rename dependencies. For example let's say that the `serde` crate has a
+bugfix that we'd like to use to its 1.\* series but we'd also like to prototype
+using a 2.0.0 version of serde we have in our git repository. To configure this
+we'd do:
+
+```toml
+[patch.crates-io]
+serde = { git = 'https://github.com/serde-rs/serde' }
+serde2 = { git = 'https://github.com/example/serde', package = 'serde', branch = 'v2' }
+```
+
+The first `serde = ...` directive indicates that serde 1.\* should be used from
+the git repository (pulling in the bugfix we need) and the second `serde2 = ...`
+directive indicates that the `serde` package should also be pulled from the `v2`
+branch of `https://github.com/example/serde`. We're assuming here that
+`Cargo.toml` on that branch mentions version 2.0.0.
+
+Note that when using the `package` key the `serde2` identifier here is actually
+ignored. We simply need a unique name which doesn't conflict with other patched
+crates.
+
 ### The `[replace]` Section
 
 This section of Cargo.toml can be used to [override dependencies][replace] with

tests/testsuite/patch.rs

@@ -1134,3 +1134,48 @@ package `[..]`
         )
         .run();
 }
+
+#[cargo_test]
+fn multipatch() {
+    Package::new("a", "1.0.0").publish();
+    Package::new("a", "2.0.0").publish();
+    let p = project()
+        .file(
+            "Cargo.toml",
+            r#"
+                [package]
+                name = "foo"
+                version = "0.0.1"
+
+                [dependencies]
+                a1 = { version = "1", package = "a" }
+                a2 = { version = "2", package = "a" }
+
+                [patch.crates-io]
+                b1 = { path = "a1", package = "a" }
+                b2 = { path = "a2", package = "a" }
+            "#,
+        )
+        .file("src/lib.rs", "pub fn foo() { a1::f1(); a2::f2(); }")
+        .file(
+            "a1/Cargo.toml",
+            r#"
+                [package]
+                name = "a"
+                version = "1.0.0"
+            "#,
+        )
+        .file("a1/src/lib.rs", "pub fn f1() {}")
+        .file(
+            "a2/Cargo.toml",
+            r#"
+                [package]
+                name = "a"
+                version = "2.0.0"
+            "#,
+        )
+        .file("a2/src/lib.rs", "pub fn f2() {}")
+        .build();
+
+    p.cargo("build").run();
+}