Small change to docs for module import syntax

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
@@ -144,8 +144,8 @@ In contrast,
 julia> import .NiceStuff
 ```
 
-brings *only* the module name into scope. Users would need to use `NiceStuff.DOG`, `NiceStuff.Dog`, and `NiceStuff.nice` to access its contents. Usually, `import ModuleName` is used in contexts when the user wants to keep the namespace clean.
-As we will see in the next section `import .NiceStuff` is equivalent to `using .NiceStuff: NiceStuff`.
+brings *only* the module name into scope. Users would need to use `NiceStuff.DOG`, `NiceStuff.Dog`, and `NiceStuff.nice` to access its contents.
+As we will see in the next section `import .NiceStuff` is equivalent to `using .NiceStuff: NiceStuff`. Usually, `import ModuleName` or `using ModuleName: ModuleName` is used in contexts when the user wants to keep the namespace clean.
 
 You can combine multiple `using` and `import` statements of the same kind in a comma-separated expression, e.g.
 
@@ -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: