1# Documentation for contributors 2 3This documentation augments the general documentation for contributing to the 4x/tools repository, described at the [repository root](../../CONTRIBUTING.md). 5 6Contributions are welcome, but since development is so active, we request that 7you file an issue and claim it before starting to work on something. Otherwise, 8it is likely that we might already be working on a fix for your issue. 9 10## Finding issues 11 12All `gopls` issues are labeled as such (see the [`gopls` label][issue-gopls]). 13Issues that are suitable for contributors are additionally tagged with the 14[`help-wanted` label][issue-wanted]. 15 16Before you begin working on an issue, please leave a comment that you are 17claiming it. 18 19## Getting started 20 21Most of the `gopls` logic is actually in the `golang.org/x/tools/internal/lsp` 22directory, so you are most likely to develop in the golang.org/x/tools module. 23 24## Build 25 26To build a version of `gopls` with your changes applied: 27 28```bash 29cd /path/to/tools/gopls 30go install 31``` 32 33To confirm that you are testing with the correct `gopls` version, check that 34your `gopls` version looks like this: 35 36```bash 37$ gopls version 38golang.org/x/tools/gopls master 39 golang.org/x/tools/gopls@(devel) 40``` 41 42## Getting help 43 44The best way to contact the gopls team directly is via the 45[#gopls-dev](https://app.slack.com/client/T029RQSE6/CRWSN9NCD) channel on the 46gophers slack. Please feel free to ask any questions about your contribution or 47about contributing in general. 48 49## Testing 50 51To run tests for just `gopls/`, run, 52 53```bash 54cd /path/to/tools/gopls 55go test ./... 56``` 57 58But, much of the gopls work involves `internal/lsp` too, so you will want to 59run both: 60 61```bash 62cd /path/to/tools 63cd gopls && go test ./... 64cd .. 65go test ./internal/lsp/... 66``` 67 68There is additional information about the `internal/lsp` tests in the 69[internal/lsp/tests `README`](https://github.com/golang/tools/blob/master/internal/lsp/tests/README.md). 70 71### Regtests 72 73gopls has a suite of regression tests defined in the `./gopls/internal/regtest` 74directory. Each of these tests writes files to a temporary directory, starts a 75separate gopls session, and scripts interactions using an editor-like API. As a 76result of this overhead they can be quite slow, particularly on systems where 77file operations are costly. 78 79Due to the asynchronous nature of the LSP, regtests assertions are written 80as 'expectations' that the editor state must achieve _eventually_. This can 81make debugging the regtests difficult. To aid with debugging, the regtests 82output their LSP logs on any failure. If your CL gets a test failure while 83running the regtests, please do take a look at the description of the error and 84the LSP logs, but don't hesitate to [reach out](#getting-help) to the gopls 85team if you need help. 86 87### CI 88 89When you mail your CL and you or a fellow contributor assigns the 90`Run-TryBot=1` label in Gerrit, the 91[TryBots](https://golang.org/doc/contribute.html#trybots) will run tests in 92both the `golang.org/x/tools` and `golang.org/x/tools/gopls` modules, as 93described above. 94 95Furthermore, an additional "gopls-CI" pass will be run by _Kokoro_, which is a 96Jenkins-like Google infrastructure for running Dockerized tests. This allows us 97to run gopls tests in various environments that would be difficult to add to 98the TryBots. Notably, Kokoro runs tests on 99[older Go versions](../README.md#supported-go-versions) that are no longer supported 100by the TryBots. Per that that policy, support for these older Go versions is 101best-effort, and test failures may be skipped rather than fixed. 102 103Kokoro runs are triggered by the `Run-TryBot=1` label, just like TryBots, but 104unlike TryBots they do not automatically re-run if the "gopls-CI" result is 105removed in Gerrit. In order to force a new run, you must upload a new patch 106set. (Technically, Googlers can force a new run on an existing patch-set via an 107internal Kokoro dashboard, but unfortunately this ability can't be made more 108generally available). 109 110## Debugging 111 112The easiest way to debug your change is to run a single `gopls` test with a 113debugger. 114 115See also [Troubleshooting](troubleshooting.md#troubleshooting). 116 117<!--TODO(rstambler): Add more details about the debug server and viewing 118telemetry.--> 119 120[issue-gopls]: https://github.com/golang/go/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Agopls "gopls issues" 121[issue-wanted]: https://github.com/golang/go/issues?utf8=✓&q=is%3Aissue+is%3Aopen+label%3Agopls+label%3A"help+wanted" "help wanted" 122