From 0fb3e2c18408cc8ff6cb87962fc13f2684d1df96 Mon Sep 17 00:00:00 2001
From: "Bryan C. Mills" <bcmills@google.com>
Date: Mon, 7 Jun 2021 17:04:32 -0400
Subject: [PATCH] doc/go1.17: add a release note for the '-compat' flag to 'go
 mod tidy'

Updates #46141

Change-Id: I7a6a84f816e3db19bb492f862366a29dc46ed2ee
Reviewed-on: https://go-review.googlesource.com/c/go/+/325910
Trust: Bryan C. Mills <bcmills@google.com>
Run-TryBot: Bryan C. Mills <bcmills@google.com>
TryBot-Result: Go Bot <gobot@golang.org>
Reviewed-by: Michael Matloob <matloob@golang.org>
---
 doc/go1.17.html | 33 +++++++++++++++++++++++++++++----
 1 file changed, 29 insertions(+), 4 deletions(-)

diff --git a/doc/go1.17.html b/doc/go1.17.html
index c1978ff1c1..ba6b8baf19 100644
--- a/doc/go1.17.html
+++ b/doc/go1.17.html
@@ -137,8 +137,9 @@ Do not send CLs removing the interior tags from such phrases.
   <!-- TODO(bcmills): replace the design-doc link with proper documentation. -->
 </p>
 
-<p><!-- golang.org/issue/45094 --> To facilitate the upgrade to lazy loading,
-  the <code>go</code> <code>mod</code> <code>tidy</code> subcommand now supports
+<p><!-- golang.org/issue/45094 -->
+  To facilitate the upgrade to lazy loading, the
+  <code>go</code> <code>mod</code> <code>tidy</code> subcommand now supports
   a <code>-go</code> flag to set or change the <code>go</code> version in
   the <code>go.mod</code> file. To enable lazy loading for an existing module
   without changing the selected versions of its dependencies, run:
@@ -149,8 +150,32 @@ Do not send CLs removing the interior tags from such phrases.
 </pre>
 
 <p><!-- golang.org/issue/46141 -->
-  TODO: Describe the <code>-compat</code> flag
-  for <code>go</code> <code>mod</code> <code>tidy</code>.
+  By default, <code>go</code> <code>mod</code> <code>tidy</code> verifies that
+  the selected versions of dependencies relevant to the main module are the same
+  versions that would be used by the prior Go release (Go 1.16 for a module that
+  spsecifies <code>go</code> <code>1.17</code>), and preserves
+  the <code>go.sum</code> entries needed by that release even for dependencies
+  that are not normally needed by other commands.
+</p>
+
+<p>
+  The <code>-compat</code> flag allows that version to be overridden to support
+  older (or only newer) versions, up to the version specified by
+  the <code>go</code> directive in the <code>go.mod</code> file. To tidy
+  a <code>go</code> <code>1.17</code> module for Go 1.17 only, without saving
+  checksums for (or checking for consistency with) Go 1.16:
+</p>
+
+<pre>
+  go mod tidy -compat=1.17
+</pre>
+
+<p>
+  Note that even if the main module is tidied with <code>-compat=1.17</code>,
+  users who <code>require</code> the module from a
+  <code>go</code> <code>1.16</code> or earlier module will still be able to
+  use it, provided that the packages use only compatible language and library
+  features.
 </p>
 
 <h4 id="module-deprecation-comments">Module deprecation comments</h4>
-- 
2.50.0