Bzlmod: More documentation about repo names and strict deps
RELNOTES:
@@ -136,6 +136,48 @@ its `module()` directive. With this information in hand, we can throw an error
when we detect that versions of the same module with different compatibility
levels exist in the resolved dependency graph.
+### Repository names
+
+In Bazel, every external dependency has a repository name. Sometimes, the same
+dependency might be used via different repository names (eg. Both
+`@io_bazel_skylib` and `@bazel_skylib` mean
+[Bazel skylib](https://github.com/bazelbuild/bazel-skylib)), or the same
+repository name might be used for different dependencies in different projects.
+
+In Bzlmod, repositories can be generated by Bazel modules and
+[module extensions](#module-extensions). To resolve repository name conflicts,
+we are embracing the [repository mapping](external.md#shadowing-dependencies)
+mechanism in the new system. Here are two important concepts:
+
+* **Canonical repository name**: The globally unique repository name for each
+ repository. This will be the directory name the repository lives in.
+ <br>It's constructed as follows (**Warning**: the canonical name format is
+ not an API you should depend on, it's subject to change at any time):
+
+ * For Bazel module repos: `<module name>.<version>`
+ <br> (eg. `@bazel_skylib.1.0.3`)
+ * For module extension repos: `<module name>.<version>.<extension name>.<repo name>`
+ <br>(eg. `@rules_cc.0.0.1.cc_configure.local_config_cc`)
+
+* **Local repository name**: The repository name to be used in the BUILD and
+ bzl files within a repo. The same dependency could have different local
+ names for different repos.
+ <br>It's determined as follows:
+
+ * For Bazel module repos: `<module name>` by default, or the name
+ specified by the `repo_name` attribute in
+ [`bazel_dep`](skylark/lib/globals.html#bazel_dep).
+ * For module extension repos: repository name introduced via
+ [`use_repo`](skylark/lib/globals.html#use_repo).
+
+Every repository has a repository mapping dictionary of its direct dependencies,
+which is a map from the local repository name to the canonical repository name.
+We use the repository mapping to resolve the repository name when constructing a
+label. Note that, there is no conflict of canonical repository names, and the
+usages of local repository names can be discovered by parsing the MODULE.bazel
+file, therefore conflicts can be easily caught and resolved without affecting
+other dependencies.
+
### Strict deps
The new dependency specification format allows us to perform stricter checks. In
@@ -143,6 +185,19 @@ particular, we now enforce that a module can only use repos created from its
direct dependencies. This helps prevent accidental and hard-to-debug breakages
when something in the transitive dependency graph changes.
+Strict deps is implemented based on
+[repository mapping](external.md#shadowing-dependencies). Basically, the
+repository mapping for each repo contains all of its *direct dependencies*, any
+other repository is not visible. Visible dependencies for each repository are
+determined as follows:
+
+* A Bazel module repo can see all repos introduced in the MODULE.bazel file
+ via [`bazel_dep`](skylark/lib/globals.html#bazel_dep) and
+ [`use_repo`](skylark/lib/globals.html#use_repo).
+* A module extension repo can see all visible dependencies of the module that
+ provides the extension, plus all other repos generated by the same module
+ extension.
+
## Registries
Bzlmod discovers dependencies by requesting their information from Bazel
