This documentation augments the general documentation for contributing to the x/tools repository, described at the repository root.
Contributions are welcome, but since development is so active, we request that you file an issue and claim it before starting to work on something. Otherwise, it is likely that we might already be working on a fix for your issue.
All gopls issues are labeled as such (see the gopls label). Issues that are suitable for contributors are additionally tagged with the help-wanted label.
Before you begin working on an issue, please leave a comment that you are claiming it.
Most of the gopls logic is actually in the golang.org/x/tools/internal/lsp directory, so you are most likely to develop in the golang.org/x/tools module.
To build a version of gopls with your changes applied:
cd /path/to/tools/gopls go install
To confirm that you are testing with the correct gopls version, check that your gopls version looks like this:
$ gopls version golang.org/x/tools/gopls master golang.org/x/tools/gopls@(devel)
The best way to contact the gopls team directly is via the #gopls-dev channel on the gophers slack. Please feel free to ask any questions about your contribution or about contributing in general.
To run tests for just gopls/, run,
cd /path/to/tools/gopls go test ./...
But, much of the gopls work involves internal/lsp too, so you will want to run both:
cd /path/to/tools cd gopls && go test ./... cd .. go test ./internal/lsp/...
There is additional information about the internal/lsp tests in the internal/lsp/tests README.
gopls has a suite of regression tests defined in the ./gopls/internal/regtest directory. Each of these tests writes files to a temporary directory, starts a separate gopls session, and scripts interactions using an editor-like API. As a result of this overhead they can be quite slow, particularly on systems where file operations are costly.
Due to the asynchronous nature of the LSP, regtests assertions are written as ‘expectations’ that the editor state must achieve eventually. This can make debugging the regtests difficult. To aid with debugging, the regtests output their LSP logs on any failure. If your CL gets a test failure while running the regtests, please do take a look at the description of the error and the LSP logs, but don't hesitate to reach out to the gopls team if you need help.
When you mail your CL and you or a fellow contributor assigns the Run-TryBot=1 label in Gerrit, the TryBots will run tests in both the golang.org/x/tools and golang.org/x/tools/gopls modules, as described above.
Furthermore, an additional “gopls-CI” pass will be run by Kokoro, which is a Jenkins-like Google infrastructure for running Dockerized tests. This allows us to run gopls tests in various environments that would be difficult to add to the TryBots. Notably, Kokoro runs tests on older Go versions that are no longer supported by the TryBots. Per that that policy, support for these older Go versions is best-effort, and test failures may be skipped rather than fixed.
Kokoro runs are triggered by the Run-TryBot=1 label, just like TryBots, but unlike TryBots they do not automatically re-run if the “gopls-CI” result is removed in Gerrit. In order to force a new run, you must upload a new patch set. (Technically, Googlers can force a new run on an existing patch-set via an internal Kokoro dashboard, but unfortunately this ability can't be made more generally available).
The easiest way to debug your change is to run can run a single gopls test with a debugger.