Skip to content

Commit

Permalink
gopls: expand on documentation about version support changes
Browse files Browse the repository at this point in the history
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 gopls@v0.15.x.

For golang/go#67936

Change-Id: Ia9f241da4a67dc0ca82532ae945751ad3c6b6f1f
Reviewed-on: https://go-review.googlesource.com/c/tools/+/592576
Reviewed-by: Alan Donovan <adonovan@google.com>
Auto-Submit: Robert Findley <rfindley@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
  • Loading branch information
findleyr committed Jun 13, 2024
1 parent b59dd37 commit 2ca6abe
Show file tree
Hide file tree
Showing 2 changed files with 69 additions and 22 deletions.
34 changes: 24 additions & 10 deletions gopls/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 gopls@v0.17.0 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 gopls@v0.17.0 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 gopls@v0.17.0, 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
Expand Down
57 changes: 45 additions & 12 deletions gopls/doc/release/v0.16.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 gopls@v0.17.0, 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 gopls@v0.17.0.

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

Expand Down Expand Up @@ -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)
Expand Down

0 comments on commit 2ca6abe

Please sign in to comment.