cmd/go: document <module>/@latest endpoint in 'go help goproxy'

Updates #32789

Change-Id: Ie5e8e3b7b6a923aa9068c8af3ac8f081bd92c830
Reviewed-on: https://go-review.googlesource.com/c/go/+/190838Reviewed-by: Bryan C. Mills <bcmills@google.com>
Run-TryBot: Bryan C. Mills <bcmills@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>

src/cmd/go/alldocs.go

@@ -2062,8 +2062,8 @@
 //
 // The GET requests sent to a Go module proxy are:
 //
-// GET $GOPROXY/<module>/@v/list returns a list of all known versions of the
-// given module, one per line.
+// GET $GOPROXY/<module>/@v/list returns a list of known versions of the given
+// module, one per line.
 //
 // GET $GOPROXY/<module>/@v/<version>.info returns JSON-formatted metadata
 // about that version of the given module.
@@ -2074,6 +2074,21 @@
 // GET $GOPROXY/<module>/@v/<version>.zip returns the zip archive
 // for that version of the given module.
 //
+// GET $GOPROXY/<module>/@latest returns JSON-formatted metadata about the
+// latest known version of the given module in the same format as
+// <module>/@v/<version>.info. The latest version should be the version of
+// the module the go command may use if <module>/@v/list is empty or no
+// listed version is suitable. <module>/@latest is optional and may not
+// be implemented by a module proxy.
+//
+// When resolving the latest version of a module, the go command will request
+// <module>/@v/list, then, if no suitable versions are found, <module>/@latest.
+// The go command prefers, in order: the semantically highest release version,
+// the semantically highest pre-release version, and the chronologically
+// most recent pseudo-version. In Go 1.12 and earlier, the go command considered
+// pseudo-versions in <module>/@v/list to be pre-release versions, but this is
+// no longer true since Go 1.13.
+//
 // To avoid problems when serving from case-sensitive file systems,
 // the <module> and <version> elements are case-encoded, replacing every
 // uppercase letter with an exclamation mark followed by the corresponding

src/cmd/go/internal/modfetch/proxy.go

@@ -38,8 +38,8 @@ can be a module proxy.
 
 The GET requests sent to a Go module proxy are:
 
-GET $GOPROXY/<module>/@v/list returns a list of all known versions of the
-given module, one per line.
+GET $GOPROXY/<module>/@v/list returns a list of known versions of the given
+module, one per line.
 
 GET $GOPROXY/<module>/@v/<version>.info returns JSON-formatted metadata
 about that version of the given module.
@@ -50,6 +50,21 @@ for that version of the given module.
 GET $GOPROXY/<module>/@v/<version>.zip returns the zip archive
 for that version of the given module.
 
+GET $GOPROXY/<module>/@latest returns JSON-formatted metadata about the
+latest known version of the given module in the same format as
+<module>/@v/<version>.info. The latest version should be the version of
+the module the go command may use if <module>/@v/list is empty or no
+listed version is suitable. <module>/@latest is optional and may not
+be implemented by a module proxy.
+
+When resolving the latest version of a module, the go command will request
+<module>/@v/list, then, if no suitable versions are found, <module>/@latest.
+The go command prefers, in order: the semantically highest release version,
+the semantically highest pre-release version, and the chronologically
+most recent pseudo-version. In Go 1.12 and earlier, the go command considered
+pseudo-versions in <module>/@v/list to be pre-release versions, but this is
+no longer true since Go 1.13.
+
 To avoid problems when serving from case-sensitive file systems,
 the <module> and <version> elements are case-encoded, replacing every
 uppercase letter with an exclamation mark followed by the corresponding