v0.17.0.md

gopls/v0.17.0

go install golang.org/x/tools/gopls@v0.17.0-pre.4

New support policies

With this release, we are narrowing our official support window to align with the Go support policy. This will reduce the considerable costs to us of testing against older Go versions, allowing us to spend more time fixing bugs and adding features that benefit the majority of gopls users who run recent versions of Go.

This narrowing is occuring in two dimensions: build compatibility refers to the versions of the Go toolchain that can be used to build gopls, and go command compatibility refers to the versions of the go command that can be used by gopls to list information about packages and modules in your workspace.

Build compatibility: the most recent major Go version

As described in the v0.16.0 release notes, building the latest version of gopls will now require the latest major version of the Go toolchain. Therefore this release (gopls@v0.17.0) must be built with Go 1.23.0 or later. Thanks to automatic toolchain upgrades, if your system Go version is at least Go 1.21.0 and you have GOTOOLCHAIN=auto set (the default), the go command will automatically download the new Go toolchain as needed, similar to upgrading a module dependency.

Go command compatibility: the 2 most recent major Go versions

The gopls@v0.17.x releases will be the final versions of gopls to nominally support integrating with more than the 2 most recent Go releases. In the past, we implied "best effort" support for up to 4 versions, though in practice we did not have resources to fix bugs that were present only with older Go versions. With gopls@v0.17.0, we narrowed this best effort support to 3 versions, primarily because users need at least Go 1.21 to benefit from automatic toolchain upgrades (see above).

Starting with gopls@v0.18.0, we will officially support integrating with only the 2 most recent major versions of the go command. This is consistent with the Go support policy. See golang/go#69321 (or this comment specifically) for details.

We won't prevent gopls from being used with older Go versions (just as we don't disallow integration with arbitrary go/packages drivers), but we won't run integration tests against older Go versions, and won't fix bugs that are only present when used with old Go versions.

Configuration Changes

• The fieldalignment analyzer, previously disabled by default, has been removed: it is redundant with the hover size/offset information displayed by v0.16.0 and its diagnostics were confusing.
• The undeclaredname analyzer has been replaced with an ordinary code action.
• The kind (identifiers) of all of gopls' code actions have changed to use more specific hierarchical names. For example, "Inline call" has changed from refactor.inline to refactor.inline.call. This allows clients to request particular code actions more precisely. The user manual now includes the identifier in the documentation for each code action.
• The experimental allowImplicitNetworkAccess setting is removed, following its deprecation in gopls@v0.16.0. See golang/go#66861 for details.

New features

Refactoring

This release contains a number of new features related to refactoring. Additionally, it fixes many bugs in existing refactoring operations, primarily related to extract, and inline.

These improvements move us toward a longer term goal of offering a more robust and complete set of refactoring tools. We still have much to do, and this effort will continue into 2025.

Move parameter refactorings

Gopls now offers code actions to move function and method parameters left or right in the function signature, updating all callers.

Unfortunately, there is no native LSP operation that provides a good user interface for arbitrary "change signature" refactoring. We plan to build such an interface within VS Code. In the short term, we have made it possible to express more complicated parameter transformations by invoking 'rename' on the 'func' keyword. This user interface is a temporary stop-gap until a better mechanism is available for LSP commands that enable client-side dialogs.

Extract declarations to new file

Gopls now offers another code action, "Extract declarations to new file" (refactor.extract.toNewFile), which moves selected code sections to a newly created file within the same package. The created filename is chosen as the first {function, type, const, var} name encountered. In addition, import declarations are added or removed as needed.

The user can invoke this code action by selecting a function name, the keywords func, const, var, type, or by placing the caret on them without selecting, or by selecting a whole declaration or multiple declarations.

In order to avoid ambiguity and surprise about what to extract, some kinds of paritial selection of a declaration cannot invoke this code action.

Extract constant

When the selection is a constant expression, gopls now offers "Extract constant" instead of "Extract variable", and generates a const declaration instead of a local variable.

Also, extraction of a constant or variable now works at top-level, outside of any function.

Generate missing method from function call

When you attempt to call a method on a type that lacks that method, the compiler will report an error like “type T has no field or method f”. Gopls now offers a new code action, “Declare missing method of T.f”, where T is the concrete type and f is the undefined method. The stub method's signature is inferred from the context of the call.

Generate a test for a function or method

If the selected chunk of code is part of a function or method declaration F, gopls will offer the "Add test for F" code action, which adds a new test for the selected function in the corresponding _test.go file. The generated test takes into account its signature, including input parameters and results.

Since this feature is implemented by the server (gopls), it is compatible with all LSP-compliant editors. VS Code users may continue to use the client-side Go: Generate Unit Tests For file/function/package command, which runs the gotests tool.

Initial support for pull diagnostics

When initialized with the option "pullDiagnostics": true, gopls will advertise support for the textDocument.diagnostic client capability, which allows editors to request diagnostics directly from gopls using a textDocument/diagnostic request, rather than wait for a textDocument/publishDiagnostics notification. This feature is off by default until the feature set of pull diagnostics is comparable to push diagnostics.

Hover improvements

The textDocument/hover response has slightly tweaked markdown rendering, and includes the following additional information:

• Hovering over a standard library symbol now displays information about the first Go release containing the symbol. For example, hovering over errors.As shows "Added in go1.13".
• Hovering over the package name in a package declaration includes additional package metadata.

Semantic token modifiers of top-level constructor of types

The semantic tokens response now includes additional modifiers for the top-level constructor of the type of each symbol: interface, struct, signature, pointer, array, map, slice, chan, string, number, bool, and invalid. Editors may use this for syntax coloring.

SignatureHelp for ident and values.

Now, function signature help can be used on any identifier with a function signature, not just within the parentheses of a function being called.

Jump to assembly definition

A Definition query on a reference to a function jumps to the function's Go func declaration. If the function is implemented in C or assembly, the function has no body. Executing a second Definition query (while already at the Go declaration) will navigate you to the assembly implementation.

yield analyzer

The new yield analyzer detects mistakes using the yield function in a Go 1.23 iterator, such as failure to check its boolean result and break out of a loop.

waitgroup analyzer

The new waitgroup analyzer detects calls to the Add method of sync.WaitGroup that are (mistakenly) made within the new goroutine, causing Add to race with Wait. (This check is equivalent to staticcheck's SA2000, but is enabled by default.)