Add doc about repo_mapping
RELNOTES: None
@@ -133,6 +133,82 @@ By default, external dependencies are fetched as needed during `bazel build`. If
you would like to disable this behavior or prefetch dependencies, use
[`bazel fetch`](http://docs.bazel.build/user-manual.html#fetch).
+## Shadowing dependencies
+
+Whenever possible, it is recommended to have a single version policy in your
+project. This is required for dependencies that you compile against and end up
+in your final binary. But for cases where this isn't true, it is possible to
+shadow dependencies. Consider the following scenario:
+
+myproject/WORKSPACE
+```python
+local_repository(
+ name = "A",
+ path = "../A",
+)
+local_repository(
+ name = "B",
+ path = "../B",
+)
+```
+
+A/WORKSPACE
+```python
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+http_archive(
+ name = "testrunner",
+ urls = ["https://github.com/testrunner/v1.zip"],
+ sha256 = "...",
+)
+```
+
+B/WORKSPACE
+```python
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+http_archive(
+ name = "testrunner",
+ urls = ["https://github.com/testrunner/v2.zip"],
+ sha256 = "..."
+)
+```
+
+Both dependencies `A` and `B` depend on `testrunner`, but they depend on
+different versions of `testrunner`. There is no reason for these test runners to
+not peacefully coexist within `myproject`, however they will clash with each
+other since they have the same name. To declare both dependencies,
+update myproject/WORKSPACE:
+```python
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+http_archive(
+ name = "testrunner-v1",
+ urls = ["https://github.com/testrunner/v1.zip"],
+ sha256 = "..."
+)
+http_archive(
+ name = "testrunner-v2",
+ urls = ["https://github.com/testrunner/v2.zip"],
+ sha256 = "..."
+)
+local_repository(
+ name = "A",
+ path = "../A",
+ repo_mapping = {"@testrunner" : "@testrunner-v1"}
+)
+local_repository(
+ name = "B",
+ path = "../B",
+ repo_mapping = {"@testrunner" : "@testrunner-v2"}
+)
+```
+
+This mechanism can also be used to join diamonds. For example if `A` and `B`
+had the same dependency but call it by different names, those dependencies can
+be joined in myproject/WORKSPACE.
+
+This behavior is currently gated behind a flag,
+`--experimental_enable_repo_mapping`.
+
+
## Using Proxies
Bazel will pick up proxy addresses from the `HTTPS_PROXY` and `HTTP_PROXY`
