[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 <jayconrod@google.com>
Reviewed-by: Bryan C. Mills <bcmills@google.com>
(cherry picked from commit b816cb2cd5f1b7cee660c6e4b85d8130b960752a)
Reviewed-on: https://go-review.googlesource.com/c/go/+/224119
TryBot-Result: Gobot Gobot <gobot@golang.org>

2 files changed, 66 insertions, 38 deletions

diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go
index 971a756b37..c2678c3dd3 100644
--- a/src/cmd/go/alldocs.go
+++ b/src/cmd/go/alldocs.go
@@ -2506,13 +2506,21 @@
 // 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
@@ -2710,22 +2718,28 @@
 //
 // 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.
 //
 //
 // Module authentication using go.sum
diff --git a/src/cmd/go/internal/modload/help.go b/src/cmd/go/internal/modload/help.go
index 66c1f70db7..bd19bb43aa 100644
--- a/src/cmd/go/internal/modload/help.go
+++ b/src/cmd/go/internal/modload/help.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.
 	`,
 }