[release-branch.go1.14] cmd/go: update 'go help modules' for automatic vendoring

* Mention vendor/modules.txt verification with -mod=vendor.
* Update "Modules and vendoring" section.

Fixes #37931

Change-Id: Ia3ee72457daabaa2fc15b7ea7427eb324c088b8f
Reviewed-on: https://go-review.googlesource.com/c/go/+/223926
Run-TryBot: Jay Conrod <[email protected]>
Reviewed-by: Bryan C. Mills <[email protected]>
(cherry picked from commit b816cb2)
Reviewed-on: https://go-review.googlesource.com/c/go/+/224119
TryBot-Result: Gobot Gobot <[email protected]>

Author: Jay Conrod

src/cmd/go/alldocs.go

@@ -176,13 +176,21 @@ not need updates, such as in a continuous integration and testing system.
 The "go get" command remains permitted to update go.mod even with -mod=readonly,
 and the "go mod" commands do not take the -mod flag (or any other build flags).
 
-If invoked with -mod=vendor, the go command assumes that the vendor
-directory holds the correct copies of dependencies and ignores
-the dependency descriptions in go.mod.
+If invoked with -mod=vendor, the go command loads packages from the main
+module's vendor directory instead of downloading modules to and loading packages
+from the module cache. The go command assumes the vendor directory holds
+correct copies of dependencies, and it does not compute the set of required
+module versions from go.mod files. However, the go command does check that
+vendor/modules.txt (generated by 'go mod vendor') contains metadata consistent
+with go.mod.
 
 If invoked with -mod=mod, the go command loads modules from the module cache
 even if there is a vendor directory present.
 
+If the go command is not invoked with a -mod flag and the vendor directory
+is present and the "go" version in go.mod is 1.14 or higher, the go command
+will act as if it were invoked with -mod=vendor.
+
 Pseudo-versions
 
 The go.mod file and the go command more generally use semantic versions as
@@ -380,22 +388,28 @@ the format of the cached downloaded packages.
 
 Modules and vendoring
 
-When using modules, the go command completely ignores vendor directories.
-
-By default, the go command satisfies dependencies by downloading modules
-from their sources and using those downloaded copies (after verification,
-as described in the previous section). To allow interoperation with older
-versions of Go, or to ensure that all files used for a build are stored
-together in a single file tree, 'go mod vendor' creates a directory named
-vendor in the root directory of the main module and stores there all the
-packages from dependency modules that are needed to support builds and
-tests of packages in the main module.
-
-To build using the main module's top-level vendor directory to satisfy
-dependencies (disabling use of the usual network sources and local
-caches), use 'go build -mod=vendor'. Note that only the main module's
-top-level vendor directory is used; vendor directories in other locations
-are still ignored.
+When using modules, the go command typically satisfies dependencies by
+downloading modules from their sources and using those downloaded copies
+(after verification, as described in the previous section). Vendoring may
+be used to allow interoperation with older versions of Go, or to ensure
+that all files used for a build are stored together in a single file tree.
+
+The command 'go mod vendor' constructs a directory named vendor in the main
+module's root directory that contains copies of all packages needed to support
+builds and tests of packages in the main module. 'go mod vendor' also
+creates the file vendor/modules.txt that contains metadata about vendored
+packages and module versions. This file should be kept consistent with go.mod:
+when vendoring is used, 'go mod vendor' should be run after go.mod is updated.
+
+If the vendor directory is present in the main module's root directory, it will
+be used automatically if the "go" version in the main module's go.mod file is
+1.14 or higher. Build commands like 'go build' and 'go test' will load packages
+from the vendor directory instead of accessing the network or the local module
+cache. To explicitly enable vendoring, invoke the go command with the flag
+-mod=vendor. To disable vendoring, use the flag -mod=mod.
+
+Unlike vendoring in GOPATH, the go command ignores vendor directories in
+locations other than the main module's root directory.
 	`,
 }