Add doc about repo_mapping

RELNOTES: None
PiperOrigin-RevId: 204948309

1 files changed, 76 insertions, 0 deletions

diff --git a/site/docs/external.md b/site/docs/external.md
index 180011eea2..96d9868838 100644
--- a/site/docs/external.md
+++ b/site/docs/external.md
@@ -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`