[7.1.0] Document best practice of avoiding extensions directly specifying repository names

site/en/external/extension.md

@@ -183,3 +183,20 @@ ensure to indicate this in the extension definition using the `os_dependent`
 and `arch_dependent` boolean attributes. This ensures that Bazel recognizes the
 need for re-evaluation if there are changes to either of them.
 
+### Only the root module should directly affect repository names
+
+Remember that when an extension creates repositories, they are created within
+the namespace of the extension. This means collisions can occur if different
+modules use the same extension and end up creating a repository with the same
+name. This often manifests as a module extension's `tag_class` having a `name`
+argument that is passed as a repository rule's `name` value.
+
+For example, say the root module, `A`, depends on module `B`. Both modules
+depend on module `mylang`. If both `A` and `B` call
+`mylang.toolchain(name="foo")`, they will both try to create a repository named
+`foo` within the `mylang` module and an error will occur.
+
+To avoid this, either remove the ability to set the repository name directly,
+or only allow the root module to do so. It's OK to allow the root module this
+ability because nothing will depend on it, so it doesn't have to worry about
+another module creating a conflicting name.