cmd/go: document go get @upgrade behavior in release notes

Fixes #33149

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

doc/go1.13.html

@@ -282,6 +282,17 @@ go env -w GOSUMDB=off
   major and minor versions as the version found in the build list.
 </p>
 
+<p><!-- CL 184440 -->
+  If a module passed as an argument to <code>go</code> <code>get</code>
+  without a version suffix is already required at a newer version than the
+  latest released version, it will remain at the newer version. This is
+  consistent with the behavior of the <code>-u</code> flag for module
+  dependencies. This prevents unexpected downgrades from pre-release versions.
+  The new version suffix <code>@upgrade</code> explicitly requests this
+  behavior. <code>@latest</code> explicitly requests the latest version
+  regardless of the current version.
+</p>
+
 <h4 id="version-validation">Version validation</h4><!-- CL 181881 -->
 
 <p>

src/cmd/go/alldocs.go

@@ -566,11 +566,14 @@
 // The first step is to resolve which dependencies to add.
 //
 // For each named package or package pattern, get must decide which version of
-// the corresponding module to use. By default, get chooses the latest tagged
+// the corresponding module to use. By default, get looks up the latest tagged
 // release version, such as v0.4.5 or v1.2.3. If there are no tagged release
-// versions, get chooses the latest tagged pre-release version, such as
-// v0.0.1-pre1. If there are no tagged versions at all, get chooses the latest
-// known commit.
+// versions, get looks up the latest tagged pre-release version, such as
+// v0.0.1-pre1. If there are no tagged versions at all, get looks up the latest
+// known commit. If the module is not already required at a later version
+// (for example, a pre-release newer than the latest release), get will use
+// the version it looked up. Otherwise, get will use the currently
+// required version.
 //
 // This default version selection can be overridden by adding an @version
 // suffix to the package argument, as in 'go get golang.org/x/text@v0.3.0'.

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

@@ -39,11 +39,14 @@ and then builds and installs them.
 The first step is to resolve which dependencies to add.
 
 For each named package or package pattern, get must decide which version of
-the corresponding module to use. By default, get chooses the latest tagged
+the corresponding module to use. By default, get looks up the latest tagged
 release version, such as v0.4.5 or v1.2.3. If there are no tagged release
-versions, get chooses the latest tagged pre-release version, such as
-v0.0.1-pre1. If there are no tagged versions at all, get chooses the latest
-known commit.
+versions, get looks up the latest tagged pre-release version, such as
+v0.0.1-pre1. If there are no tagged versions at all, get looks up the latest
+known commit. If the module is not already required at a later version
+(for example, a pre-release newer than the latest release), get will use
+the version it looked up. Otherwise, get will use the currently
+required version.
 
 This default version selection can be overridden by adding an @version
 suffix to the package argument, as in 'go get golang.org/x/text@v0.3.0'.