.config/coc/extensions/coc-go-data/tools/pkg/mod/golang.org/x/tools/gopls@v0.6.9/doc/contributing.md

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