gopls: expand on documentation about version support changes

Users unfamiliar with the subtleties of version support are rightly
confused by our current documentation. Try to clarify, by defining terms
more precisely and being sure to emphasize that language version support
is unchanged.

Also, add a section for the new stdversions analyzer, which is not
present in [email protected].

For golang/go#67936

Change-Id: Ia9f241da4a67dc0ca82532ae945751ad3c6b6f1f
Reviewed-on: https://go-review.googlesource.com/c/tools/+/592576
Reviewed-by: Alan Donovan <[email protected]>
Auto-Submit: Robert Findley <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>

Author: findleyr

gopls/README.md

@@ -80,16 +80,30 @@ that it officially supports only the two most recent major Go releases. Until
 August 2024, the Go team will also maintain best-effort support for the last
 4 major Go releases, as described in [issue #39146](https://go.dev/issues/39146).
 
-Starting with the release of Go 1.23.0 and [email protected] in August 2024, the
-gopls build will depend on the latest version of Go. However, due to the
-[forward compatibility](https://go.dev/blog/toolchain) support added to the
-`go` command in Go 1.21, as long as Go 1.21 or later are used to install gopls,
-the toolchain upgrade will be handled automatically, just like any other
-dependency. Gopls will continue to support integrating with the three most
-recent major Go releases of the `go` command. See
-[issue #65917](https://go.dev/issue/65917) for more details.
-
-Maintaining support for legacy versions of Go caused
+When using gopls, there are three versions to be aware of:
+1. The _gopls build go version_: the version of Go used to build gopls.
+2. The _go command version_: the version of the go list command executed by
+   gopls to load information about your workspace.
+3. The _language version_: the version in the go directive of the current
+   file's enclosing go.mod file, which determines the file's Go language
+   semantics.
+
+Starting with the release of Go 1.23.0 and [email protected] in August 2024, we
+will only support the most recent Go version as the _gopls build go version_.
+However, due to the [forward compatibility](https://go.dev/blog/toolchain)
+support added in Go 1.21, as long as Go 1.21 or later are used to install
+gopls, any necessary toolchain upgrade will be handled automatically, just like
+any other dependency.
+
+Additionally, starting with [email protected], the _go command version_ will narrow
+from 4 versions to 3. This is more consistent with the Go Release Policy.
+
+Gopls supports **all** Go versions as its _language version_, by providing
+compiler errors based on the language version and filtering available standard
+library symbols based on the standard library APIs available at that Go
+version.
+
+Maintaining support for building gopls with legacy versions of Go caused
 [significant friction](https://go.dev/issue/50825) for gopls maintainers and
 held back other improvements. If you are unable to install a supported version
 of Go on your system, you can still install an older version of gopls. The

gopls/doc/release/v0.16.0.md

@@ -10,25 +10,47 @@ version of gopls to support Go 1.23. To install it, run:
 
 ## New support policy; end of support for Go 1.19 and Go 1.20
 
-This is the last release of gopls that may be built and used with Go 1.19 or Go
+**TL;DR: We are narrowing gopls' support window, but this is unlikely to
+affect you as long as you use at least Go 1.21 to build gopls. This doesn't
+affect gopls' support for the code you are writing.**
+
+This is the last release of gopls that may be built with Go 1.19 or Go 1.20,
+and also the last to support integrating with go command versions 1.19 and
 1.20. If built or used with either of these Go versions, it will display
 a message advising the user to upgrade.
 
+When using gopls, there are three versions to be aware of:
+1. The _gopls build go version_: the version of Go used to build gopls.
+2. The _go command version_: the version of the go list command executed by
+   gopls to load information about your workspace.
+3. The _language version_: the version in the go directive of the current
+   file's enclosing go.mod file, which determines the file's Go language
+   semantics.
+
+This gopls release, v0.16.0, is the final release to support Go 1.19 and Go
+1.20 as the _gopls build go version_ or _go command version_. There is no
+change to gopls' support for all _language versions_--in fact this support has
+somewhat improved with the addition of the `stdversion` analyzer (see below).
+
 Starting with [email protected], which will be released after Go 1.23.0 is released
-in August, installing gopls will require the latest version of the Go
-toolchain. Thanks to the [forward compatibility](https://go.dev/blog/toolchain)
+in August, gopls will only support the latest version of Go as the
+_gopls build go version_.
+However, thanks to the [forward compatibility](https://go.dev/blog/toolchain)
 added to Go 1.21, any necessary toolchain upgrade should be handled
-automatically for users of Go 1.21 or later. This restriction is for _building_
-gopls only -- we will continue to support command line integration with the
-last three major Go versions. Nonetheless, this is fewer than our previous policy
-of gopls supporting the last four major Go versions of installed toolchains.
+automatically for users of Go 1.21 or later, just like any other dependency.
+Additionally, we are reducing our _go command version_ support window from
+4 versions to 3. Note that this means if you have at least Go 1.21 installed on
+your system, you should still be able to `go install` and use [email protected].
+
+We have no plans to ever change our _language version_ support: we expect that
+gopls will always support developing programs that target _any_ Go version.
 
-See the newly updated
+By focusing on building gopls with the latest Go version, we can significantly
+reduce our maintenance burden and help improve the stability of future gopls
+releases. See the newly updated
 [support policy](https://github.com/golang/tools/tree/master/gopls#support-policy)
-for details. We expect that this change will significantly reduce our
-maintenance burden, and will help improve the stability of future gopls
-releases. Please comment on [issue #65917](https://go.dev/issue/65917) if you
-have concerns about this change.
+for details. Please comment on [issue #65917](https://go.dev/issue/65917) if
+you have concerns about this change.
 
 ## Configuration Changes
 
@@ -177,6 +199,17 @@ func (s S) set(x int) {
 }
 ```
 
+### `stdversion` analyzer
+
+The new
+[`stdversion`](https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/stdversion)
+analyzer warns about the use of too-new standard library symbols based on the
+version of the `go` directive in your `go.mod` file. This improves our support
+for older _language versions_ (see above), even when gopls is built with
+a recent Go version.
+
+TODO: add a screenshot demonstrating the new diagnostics
+
 ### Two more vet analyzers
 
 The [framepointer](https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/framepointer)