diff --git a/doc/go1.17.html b/doc/go1.17.html index 48811e6b679..a8307bacac2 100644 --- a/doc/go1.17.html +++ b/doc/go1.17.html @@ -134,35 +134,54 @@ Do not send CLs removing the interior tags from such phrases.

Go command

-

Lazy module loading

+ +

Pruned module graphs in go 1.17 modules

+ If a module specifies go 1.17 or higher, the module + graph includes only the immediate dependencies of + other go 1.17 modules, not their full transitive + dependencies. (See Module graph pruning + for more detail.) +

+ +

+ For the go command to correctly resolve transitive imports using + the pruned module graph, the go.mod file for each module needs to + include more detail about the transitive dependencies relevant to that module. If a module specifies go 1.17 or higher in its - go.mod file, its transitive requirements are now loaded lazily, - avoiding the need to download or read go.mod files for - otherwise-irrelevant dependencies. To support lazy loading, in Go 1.17 modules - the go command maintains explicit requirements in - the go.mod file for every dependency that provides any package - transitively imported by any package or test within the module. - See the design - document for more detail. - + go.mod file, its go.mod file now contains an + explicit require + directive for every module that provides a transitively-imported package. + (In previous versions, the go.mod file typically only included + explicit requirements for directly-imported packages.) +

+ +

+ Since the expanded go.mod file needed for module graph pruning + includes all of the dependencies needed to load the imports of any package in + the main module, if the main module specifies + go 1.17 or higher the go tool no longer + reads (or even downloads) go.mod files for dependencies if they + are not needed in order to complete the requested command. + (See Lazy loading.)

- Because the number of additional explicit requirements in the go.mod file may - be substantial, in a Go 1.17 module the newly-added requirements - on indirect dependencies are maintained in a - separate require block from the block containing direct - dependencies. + Because the number of explicit requirements may be substantially larger in an + expanded Go 1.17 go.mod file, the newly-added requirements + on indirect dependencies in a go 1.17 + module are maintained in a separate require block from the block + containing direct dependencies.

- To facilitate the upgrade to lazy loading, the - go mod tidy subcommand now supports - a -go flag to set or change the go version in - the go.mod file. To enable lazy loading for an existing module - without changing the selected versions of its dependencies, run: + To facilitate the upgrade to Go 1.17 pruned module graphs, the + go mod tidy + subcommand now supports a -go flag to set or change + the go version in the go.mod file. To convert + the go.mod file for an existing module to Go 1.17 without + changing the selected versions of its dependencies, run: 

@@ -199,10 +218,10 @@ Do not send CLs removing the interior tags from such phrases.
 

 
 

-  The go mod graph subcommand also
-  supports the -go flag, which causes it to report the graph as
-  seen by the indicated Go version, showing dependencies that may otherwise be
-  pruned out by lazy loading.
+  The go mod graph
+  subcommand also supports the -go flag, which causes it to report
+  the graph as seen by the indicated Go version, showing dependencies that may
+  otherwise be pruned out.
 

 
 
Module deprecation comments

@@ -270,7 +289,8 @@ Do not send CLs removing the interior tags from such phrases.
 
 

   If the main module specifies go 1.17 or higher,
-  go mod vendor now annotates
+  go mod vendor
+  now annotates
   vendor/modules.txt with the go version indicated by
   each vendored module in its own go.mod file. The annotated
   version is used when building the module's packages from vendored source code.