From 66568f37fe084327c8589659fb5e578ed4db70dd Mon Sep 17 00:00:00 2001 From: Rob Findley Date: Tue, 5 Jan 2021 10:53:14 -0500 Subject: [PATCH] gopls/doc: add additional information on CI in contributing.md Also add some documentation on the regression tests, to help if/when contributors hit regtest failures. Change-Id: I9dbff91cbbe58742848f15467d3d6356189d4e3c Reviewed-on: https://go-review.googlesource.com/c/tools/+/281672 Trust: Robert Findley Run-TryBot: Robert Findley gopls-CI: kokoro TryBot-Result: Go Bot Reviewed-by: Rebecca Stambler --- gopls/doc/contributing.md | 47 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 45 insertions(+), 2 deletions(-) diff --git a/gopls/doc/contributing.md b/gopls/doc/contributing.md index 89b42257d2..091e2983ec 100644 --- a/gopls/doc/contributing.md +++ b/gopls/doc/contributing.md @@ -1,6 +1,11 @@ # Documentation for contributors -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. +This documentation augments the general documentation for contributing to the +x/tools repository, described at the [repository root](../CONTRIBUTING.md). + +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. ## Finding issues @@ -14,6 +19,13 @@ Before you begin working on an issue, please leave a comment that you are claimi Provide information to get contributors up and running here ---> +## Getting help + +The best way to contact the gopls team directly is via the +[#gopls-dev](https://app.slack.com/client/T029RQSE6/CRWSN9NCD) channel on the +gophers slack. Please feel free to ask any questions about your contribution or +about contributing in general. + ## Testing To run tests for just `gopls/`, run, @@ -33,6 +45,37 @@ cd .. go test ./internal/lsp/... ``` +### Regtests + +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](#getting-help) to the gopls +team if you need help. + +### CI + +When you mail your CL and you or a fellow contributor assigns the +`Run-TryBot=1` label in Gerrit, the +[TryBots](https://golang.org/doc/contribute.html#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](user.md#supported-go-versions) that are no longer supported +by the TryBots. + ## Debugging [issue-gopls]: https://github.com/golang/go/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Agopls "gopls issues" -[issue-wanted]: https://github.com/golang/go/issues?utf8=✓&q=is%3Aissue+is%3Aopen+label%3Agopls+label%3A"help+wanted" "help wanted" \ No newline at end of file +[issue-wanted]: https://github.com/golang/go/issues?utf8=✓&q=is%3Aissue+is%3Aopen+label%3Agopls+label%3A"help+wanted" "help wanted"