cmd/go: additional doc-inspired tests and bug fixes

Additional tests and bug fixes realized while writing go.dev/doc/gotoolchain (CL 500775).

- Handle go get [email protected] (resolve to latest patch release, same as go get [email protected]).
  (See modload/query.go and gover/mod.go.)

- Handle go get go@patch toolchain@patch.
  (See modload/query.go and gover/mod.go.)

- Remove prefix-goVERSION-suffix form for toolchain name,
  standardizing on goVERSION-suffix.
  I have no good explanation for having two forms, so simplify to one.
  (See vendor and gover.)

- Fail toolchain downloads when GOSUMDB=off.
  Because toolchain downloads cannot always be predicted
  (especially during switching rather than selection),
  they cannot be listed in go.sum.
  We rely on the checksum database for integrity of the download,
  especially if proxied. If the checksum database is disabled,
  this integrity check won't happen, so fail toolchain downloads.
  (See modfetch/sumdb.go and script/gotoolchain_net.txt)

- Use names from documentation in package toolchain
  (Select, Switch; SwitchTo renamed to Exec to avoid both names;
  reqs.go renamed to switch.go; toolchain.go renamed to select.go.)

- Make "go env GOTOOLCHAIN" and "go env -w GOTOOLCHAIN"
  work even when GOTOOLCHAIN is misconfigured.
  (See special case at top of Select in select.go.)

- Clarify what goInstallVersion does
  (report whether this is go install or go run pkg@version)
  and explain the potential version switch more clearly.
  Use the Switcher directly instead of reimplementing it.
  (See select.go.)

- Document go@ and toolchain@ forms in go help get,
  linking to go.dev/doc/toolchain.
  (See modget/get.go.)

- Update URL of documentation in $GOROOT/go.env.

For #57001.

Change-Id: I895ef3519ff95db8710ed23b36ebaf4f648120cb
Reviewed-on: https://go-review.googlesource.com/c/go/+/500797
Reviewed-by: Michael Matloob <[email protected]>
Run-TryBot: Russ Cox <[email protected]>
TryBot-Bypass: Russ Cox <[email protected]>

Author: rsc

go.env

@@ -8,5 +8,5 @@ GOPROXY=https://proxy.golang.org,direct
 GOSUMDB=sum.golang.org
 
 # Automatically download newer toolchains as directed by go.mod files.
-# See https://go.dev/s/gotoolchain for details.
+# See https://go.dev/doc/toolchain for details.
 GOTOOLCHAIN=auto

src/cmd/go/alldocs.go

@@ -84,6 +84,9 @@ func ModIsValid(path, vers string) bool {
 // The caller is assumed to have checked that ModIsValid(path, vers) is true.
 func ModIsPrefix(path, vers string) bool {
 	if IsToolchain(path) {
+		if path == "toolchain" {
+			return IsLang(FromToolchain(vers))
+		}
 		return IsLang(vers)
 	}
 	// Semver
@@ -110,3 +113,15 @@ func ModIsPrerelease(path, vers string) bool {
 	}
 	return semver.Prerelease(vers) != ""
 }
+
+// ModMajorMinor returns the "major.minor" truncation of the version v,
+// for use as a prefix in "@patch" queries.
+func ModMajorMinor(path, vers string) string {
+	if IsToolchain(path) {
+		if path == "toolchain" {
+			return "go" + Lang(FromToolchain(vers))
+		}
+		return Lang(vers)
+	}
+	return semver.MajorMinor(vers)
+}

src/cmd/go/internal/gover/mod.go

@@ -14,20 +14,17 @@ import (
 
 // FromToolchain returns the Go version for the named toolchain,
 // derived from the name itself (not by running the toolchain).
-// A toolchain is named "goVERSION" or "anything-goVERSION".
+// A toolchain is named "goVERSION".
 // A suffix after the VERSION introduced by a +, -, space, or tab is removed.
 // Examples:
 //
 //	FromToolchain("go1.2.3") == "1.2.3"
 //	FromToolchain("go1.2.3-bigcorp") == "1.2.3"
-//	FromToolchain("gccgo-go1.23rc4") == "1.23rc4"
 //	FromToolchain("invalid") == ""
 func FromToolchain(name string) string {
 	var v string
 	if strings.HasPrefix(name, "go") {
 		v = name[2:]
-	} else if i := strings.Index(name, "-go"); i >= 0 {
-		v = name[i+3:]
 	} else {
 		return ""
 	}

src/cmd/go/internal/gover/toolchain.go

@@ -14,6 +14,6 @@ var fromToolchainTests = []testCase1[string, string]{
 	{"go1.2.3+bigcorp", ""},
 	{"go1.2.3-bigcorp", "1.2.3"},
 	{"go1.2.3-bigcorp more text", "1.2.3"},
-	{"gccgo-go1.23rc4", "1.23rc4"},
-	{"gccgo-go1.23rc4-bigdwarf", "1.23rc4"},
+	{"gccgo-go1.23rc4", ""},
+	{"gccgo-go1.23rc4-bigdwarf", ""},
 }

src/cmd/go/internal/gover/toolchain_test.go

@@ -33,6 +33,14 @@ import (
 
 // useSumDB reports whether to use the Go checksum database for the given module.
 func useSumDB(mod module.Version) bool {
+	if mod.Path == "golang.org/toolchain" {
+		// Downloaded toolchains cannot be listed in go.sum,
+		// so we require checksum database lookups even if
+		// GOSUMDB=off or GONOSUMDB matches the pattern.
+		// If GOSUMDB=off, then the eventual lookup will fail
+		// with a good error message.
+		return true
+	}
 	return cfg.GOSUMDB != "off" && !module.MatchPrefixPatterns(cfg.GONOSUMDB, mod.Path)
 }
 
@@ -70,6 +78,10 @@ func dbDial() (dbName string, db *sumdb.Client, err error) {
 		gosumdb = "sum.golang.org https://sum.golang.google.cn"
 	}
 
+	if gosumdb == "off" {
+		return "", nil, fmt.Errorf("checksum database disabled by GOSUMDB=off")
+	}
+
 	key := strings.Fields(gosumdb)
 	if len(key) >= 1 {
 		if k := knownGOSUMDB[key[0]]; k != "" {

src/cmd/go/internal/modfetch/sumdb.go

@@ -72,6 +72,14 @@ To remove a dependency on a module and downgrade modules that require it:
 
 	go get example.com/mod@none
 
+To upgrade the minimum required Go version to the latest released Go version:
+
+	go get go@latest
+
+To upgrade the Go toolchain to the latest patch release of the current Go toolchain:
+
+	go get toolchain@patch
+
 See https://golang.org/ref/mod#go-get for details.
 
 In earlier versions of Go, 'go get' was used to build and install packages.
@@ -106,6 +114,9 @@ from a repository.
 
 For more about modules, see https://golang.org/ref/mod.
 
+For more about using 'go get' to update the minimum Go version and
+suggested Go toolchain, see https://go.dev/doc/toolchain.
+
 For more about specifying packages, see 'go help packages'.
 
 This text describes the behavior of get using modules to manage source

src/cmd/go/internal/modget/get.go

@@ -393,7 +393,7 @@ func newQueryMatcher(path string, query, current string, allowed AllowedFunc) (*
 			qm.mayUseLatest = true
 		} else {
 			qm.mayUseLatest = module.IsPseudoVersion(current)
-			qm.prefix = semver.MajorMinor(current) + "."
+			qm.prefix = gover.ModMajorMinor(qm.path, current) + "."
 			qm.filter = func(mv string) bool { return gover.ModCompare(qm.path, mv, current) >= 0 }
 		}