all: document vendoring in the standard library

Added documentation that explains special cases for vendored packages
in the standard library and provides instructions for updating vendor
directories.

Fixes #31806

Change-Id: Ib697ed18eae28023ab0bfb9f4d250992c393571d
Reviewed-on: https://go-review.googlesource.com/c/go/+/174999
Reviewed-by: Bryan C. Mills <bcmills@google.com>

diff --git a/src/README.vendor b/src/README.vendor
new file mode 100644 (file)
index 0000000..c802653
--- /dev/null
+++ b/src/README.vendor
@@ -0,0 +1,54 @@
+Vendoring in std and cmd
+========================
+
+The Go command maintains copies of external packages needed by the
+standard library in the src/vendor and src/cmd/vendor directories.
+
+In GOPATH mode, imports of vendored packages are resolved to these
+directories following normal vendor directory logic
+(see golang.org/s/go15vendor).
+
+In module mode, std and cmd are modules (defined in src/go.mod and
+src/cmd/go.mod). When a package outside std or cmd is imported
+by a package inside std or cmd, the import path is interpreted
+as if it had a "vendor/" prefix. For example, within "crypto/tls",
+an import of "golang.org/x/crypto/cryptobyte" resolves to
+"vendor/golang.org/x/crypto/cryptobyte". When a package with the
+same path is imported from a package outside std or cmd, it will
+be resolved normally. Consequently, a binary may be built with two
+copies of a package at different versions if the package is
+imported normally and vendored by the standard library.
+
+Vendored packages are internally renamed with a "vendor/" prefix
+to preserve the invariant that all packages have distinct paths.
+This is necessary to avoid compiler and linker conflicts. Adding
+a "vendor/" prefix also maintains the invariant that standard
+library packages begin with a dotless path element.
+
+The module requirements of std and cmd do not influence version
+selection in other modules. They are only considered when running
+module commands like 'go get' and 'go mod vendor' from a directory
+in GOROOT/src.
+
+Maintaining vendor directories
+==============================
+
+Before updating vendor directories, ensure that module mode is enabled.
+Make sure GO111MODULE=off is not set ('on' or 'auto' should work).
+
+Requirements may be added, updated, and removed with 'go get'.
+The vendor directory may be updated with 'go mod vendor'.
+A typical sequence might be:
+
+    cd src
+    go get -m golang.org/x/net@latest
+    go mod tidy
+    go mod vendor
+
+Use caution when passing '-u' to 'go get'. The '-u' flag updates
+modules providing all transitively imported packages, not just
+the target module.
+
+Note that 'go mod vendor' only copies packages that are transitively
+imported by packages in the current module. If a new package is needed,
+it should be imported before running 'go mod vendor'.

diff --git a/src/cmd/README.vendor b/src/cmd/README.vendor
new file mode 100644 (file)
index 0000000..ac0df5e
--- /dev/null
+++ b/src/cmd/README.vendor
@@ -0,0 +1,2 @@
+See src/README.vendor for information on loading vendored packages
+and updating the vendor directory.