Add docs and news.

Author: maleadt

NEWS.md

@@ -12,6 +12,9 @@ New language features
 Language changes
 ----------------
 
+* Specifying a path in `JULIA_DEPOT_PATH` now results in the expansion of empty strings to
+  omit the default user depot ([#51448]).
+
 Compiler/Runtime improvements
 -----------------------------
 * Updated GC heuristics to count allocated pages instead of individual objects ([#50144]).

doc/src/manual/environment-variables.md

@@ -125,23 +125,30 @@ as Julia's code loading mechanisms, look for package registries, installed
 packages, named environments, repo clones, cached compiled package images,
 configuration files, and the default location of the REPL's history file.
 
-Unlike the shell `PATH` variable but similar to [`JULIA_LOAD_PATH`](@ref JULIA_LOAD_PATH), empty entries in
-[`JULIA_DEPOT_PATH`](@ref JULIA_DEPOT_PATH) are expanded to the default value of `DEPOT_PATH`. This allows
-easy appending, prepending, etc. of the depot path value in shell scripts regardless
-of whether [`JULIA_DEPOT_PATH`](@ref JULIA_DEPOT_PATH) is already set or not. For example, to prepend the
-directory `/foo/bar` to `DEPOT_PATH` just do
+Unlike the shell `PATH` variable but similar to [`JULIA_LOAD_PATH`](@ref JULIA_LOAD_PATH),
+empty entries in [`JULIA_DEPOT_PATH`](@ref JULIA_DEPOT_PATH) are expanded to the default
+value of `DEPOT_PATH`, excluding the user depot. This allows easy overriding of the user
+depot, while still retaining access to resources that are bundled with Julia, like cache
+files, artifacts, etc. For example, to switch the user depot to `/foo/bar` just do
 ```sh
-export JULIA_DEPOT_PATH="/foo/bar:$JULIA_DEPOT_PATH"
+export JULIA_DEPOT_PATH="/foo/bar:"
 ```
-If the [`JULIA_DEPOT_PATH`](@ref JULIA_DEPOT_PATH) environment variable is already set, its old value will be
-prepended with `/foo/bar`. On the other hand, if [`JULIA_DEPOT_PATH`](@ref JULIA_DEPOT_PATH) is not set, then
-it will be set to `/foo/bar:` which will have the effect of prepending `/foo/bar` to
-the default depot path. If [`JULIA_DEPOT_PATH`](@ref JULIA_DEPOT_PATH) is set to the empty string, it expands
-to an empty `DEPOT_PATH` array. In other words, the empty string is interpreted as a
-zero-element array, not a one-element array of the empty string. This behavior was
-chosen so that it would be possible to set an empty depot path via the environment
-variable. If you want the default depot path, either unset the environment variable
-or if it must have a value, set it to the string `:`.
+All package operations, like cloning registrise or installing packages, will now write to
+`/foo/bar`, but since the empty entry is expanded to the default system depot, any bundled
+resources will still be available. If you really only want to use the depot at `/foo/bar`,
+and not load any bundled resources, simply set the environment variable to `/foo/bar`
+without the trailing colon.
+
+There are two exceptions to the above rule. First, if [`JULIA_DEPOT_PATH`](@ref
+JULIA_DEPOT_PATH) is set to the empty string, it expands to an empty `DEPOT_PATH` array. In
+other words, the empty string is interpreted as a zero-element array, not a one-element
+array of the empty string. This behavior was chosen so that it would be possible to set an
+empty depot path via the environment variable.
+
+Second, if no user depot is specified in [`JULIA_DEPOT_PATH`](@ref JULIA_DEPOT_PATH), then
+the empty entry is expanded to the default depot *including* the user depot. This makes
+it possible to use the default depot, as if the environment variable was unset, by setting
+it to the string `:`.
 
 !!! note