recommend explicit using Foo: Foo, ... in package code (was: "using considered harmful")

base/docs/basedocs.jl

@@ -37,6 +37,14 @@ kw"help", kw"Julia", kw"julia", kw""
 available for direct use. Names can also be used via dot syntax (e.g. `Foo.foo` to access
 the name `foo`), whether they are `export`ed or not.
 See the [manual section about modules](@ref modules) for details.
+
+!!! note
+    When two or more packages/modules export a name and that name does not refer to the
+    same thing in each of the packages, and the packages are loaded via `using` without
+    an explicit list of names, it is an error to reference that name without qualification.
+    It is thus recommended that code intended to be forward-compatible with future versions
+    of its dependencies and of Julia, e.g. code in released packages, list the names it
+    uses from each loaded package, e.g. `using Foo: Foo, f` rather than `using Foo`.
 """
 kw"using"
 

doc/src/manual/modules.md

@@ -112,7 +112,7 @@ and above. To maintain compatibility with Julia 1.10 and below, use the `@compat
 
 ### Standalone `using` and `import`
 
-Possibly the most common way of loading a module is `using ModuleName`. This [loads](@ref
+For interactive use, the most common way of loading a module is `using ModuleName`. This [loads](@ref
 code-loading) the code associated with `ModuleName`, and brings
 
 1. the module name
@@ -168,6 +168,16 @@ Importantly, the module name `NiceStuff` will *not* be in the namespace. If you
 julia> using .NiceStuff: nice, DOG, NiceStuff
 ```
 
+Qualifying the names being used as in `using Foo: Foo, f` is
+recommended over plain `using Foo` for released packages, and other
+code which is meant to be re-used in the future with updated dependencies
+or future versions of julia.
+
+The reason for this is if another dependency starts to export one of the
+same names as `Foo` and you attempt to use that name, then previously working
+code will error due to an ambiguity in which package the name should be
+taken from.
+
 Julia has two forms for seemingly the same thing because only `import ModuleName: f` allows adding methods to `f`
 *without a module path*.
 That is to say, the following example will give an error: