cmd/go/internal/get: improve -insecure deprecation docs

Updates #37519

Change-Id: I212607f1839b729d7da24b1258e56997b13ad830
GitHub-Last-Rev: db6d3c835b
GitHub-Pull-Request: golang/go#41613
Reviewed-on: https://go-review.googlesource.com/c/go/+/257157
Run-TryBot: Bryan C. Mills <bcmills@google.com>
TryBot-Result: Go Bot <gobot@golang.org>
Trust: Jay Conrod <jayconrod@google.com>
Trust: Bryan C. Mills <bcmills@google.com>
Reviewed-by: Bryan C. Mills <bcmills@google.com>
Reviewed-by: Jay Conrod <jayconrod@google.com>

doc/go1.16.html

@@ -90,12 +90,13 @@ Do not send CLs removing the interior tags from such phrases.
 
 <p><!-- golang.org/issue/37519 -->
   The <code>go</code> <code>get</code> <code>-insecure</code> flag is
-  deprecated and will be removed in a future version. The <code>GOINSECURE</code>
+  deprecated and will be removed in a future version. This flag permits
-  environment variable should be used instead, since it provides control
+  fetching from repositories and resolving custom domains using insecure
-  over which modules may be retrieved using an insecure scheme. Unlike the
+  schemes such as HTTP, and also bypassess module sum validation using the
-  <code>-insecure</code> flag, <code>GOINSECURE</code> does not disable module
+  checksum database. To permit the use of insecure schemes, use the
-  sum validation using the checksum database. The <code>GOPRIVATE</code> or
+  <code>GOINSECURE</code> environment variable instead. To bypass module
-  <code>GONOSUMDB</code> environment variables may be used instead.
+  sum validation, use <code>GOPRIVATE</code> or <code>GONOSUMDB</code>.
+  See <code>go</code> <code>help</code> <code>environment</code> for details.
 </p>
 
 <h4 id="all-pattern">The <code>all</code> pattern</h4>

src/cmd/go/alldocs.go

@@ -662,13 +662,12 @@
 // this automatically as well.
 //
 // The -insecure flag permits fetching from repositories and resolving
-// custom domains using insecure schemes such as HTTP. Use with caution.
+// custom domains using insecure schemes such as HTTP, and also bypassess
+// module sum validation using the checksum database. Use with caution.
 // This flag is deprecated and will be removed in a future version of go.
-// The GOINSECURE environment variable is usually a better alternative, since
+// To permit the use of insecure schemes, use the GOINSECURE environment
-// it provides control over which modules may be retrieved using an insecure
+// variable instead. To bypass module sum validation, use GOPRIVATE or
-// scheme. It should be noted that the -insecure flag also turns the module
+// GONOSUMDB. See 'go help environment' for details.
-// checksum validation off. GOINSECURE does not do that, use GONOSUMDB.
-// See 'go help environment' for details.
 //
 // The second step is to download (if needed), build, and install
 // the named packages.
@@ -2211,8 +2210,8 @@
 // The -insecure flag permits fetching from repositories and resolving
 // custom domains using insecure schemes such as HTTP. Use with caution.
 // This flag is deprecated and will be removed in a future version of go.
-// The GOINSECURE environment variable is usually a better alternative, since
+// The GOINSECURE environment variable should be used instead, since it
-// it provides control over which modules may be retrieved using an insecure
+// provides control over which packages may be retrieved using an insecure
 // scheme. See 'go help environment' for details.
 //
 // The -t flag instructs get to also download the packages required to build

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

@@ -46,8 +46,8 @@ before resolving dependencies or building the code.
 The -insecure flag permits fetching from repositories and resolving
 custom domains using insecure schemes such as HTTP. Use with caution.
 This flag is deprecated and will be removed in a future version of go.
-The GOINSECURE environment variable is usually a better alternative, since
+The GOINSECURE environment variable should be used instead, since it
-it provides control over which modules may be retrieved using an insecure
+provides control over which packages may be retrieved using an insecure
 scheme. See 'go help environment' for details.
 
 The -t flag instructs get to also download the packages required to build

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

@@ -115,13 +115,12 @@ require downgrading other dependencies, and 'go get' does
 this automatically as well.
 
 The -insecure flag permits fetching from repositories and resolving
-custom domains using insecure schemes such as HTTP. Use with caution.
+custom domains using insecure schemes such as HTTP, and also bypassess
+module sum validation using the checksum database. Use with caution.
 This flag is deprecated and will be removed in a future version of go.
-The GOINSECURE environment variable is usually a better alternative, since
+To permit the use of insecure schemes, use the GOINSECURE environment
-it provides control over which modules may be retrieved using an insecure
+variable instead. To bypass module sum validation, use GOPRIVATE or
-scheme. It should be noted that the -insecure flag also turns the module
+GONOSUMDB. See 'go help environment' for details.
-checksum validation off. GOINSECURE does not do that, use GONOSUMDB.
-See 'go help environment' for details.
 
 The second step is to download (if needed), build, and install
 the named packages.