Skip to content

Commit e0d2015

Browse files
heschiheschi
committed
gopls/doc: rewrite troubleshooting.md
Rewrite the troubleshooting doc to be (hopefully) more helpful. I tried to start from the assumption that the user had made a mistake rather than that there was a bug in gopls. In particular, they're now instructed to check for mistakes before updating gopls, and to try Gophers Slack before filing a bug. In general, I tried to adopt a more conversational voice as the gopls authors, which I hope will make it more readable. Once this looks good I'll do the VS Code version. Change-Id: Ie36ad47af9e96b734475f8abe157ab3ad9c8cf09 Reviewed-on: https://go-review.googlesource.com/c/tools/+/283934 Trust: Heschi Kreinick <[email protected]> Reviewed-by: Robert Findley <[email protected]> Reviewed-by: Rebecca Stambler <[email protected]>
1 parent d78b04b commit e0d2015

File tree

1 file changed

+24
-61
lines changed

1 file changed

+24
-61
lines changed

‎gopls/doc/troubleshooting.md

Lines changed: 24 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,85 +1,48 @@
11
# Troubleshooting
22

3-
If you suspect that `gopls` is crashing or not working correctly, please follow the [troubleshooting steps](#steps) below.
3+
If you suspect that `gopls` is crashing or not working correctly, please follow the troubleshooting steps below.
44

5-
If `gopls` is using too much memory, please follow the steps under [Memory usage](#memory-usage).
5+
If `gopls` is using too much memory, please follow the steps under [Memory usage](#debug-memory-usage).
66

77
## Steps
88

9-
<!--- TODO: troubleshooting
10-
describe more basic and optional trouble shooting steps
11-
like checking you opened the module root
12-
and using the debug pages
13-
--->
9+
VS Code users should follow [their troubleshooting guide](https://github.com/golang/vscode-go/blob/master/docs/troubleshooting.md), which has more a more specific version of these instructions.
1410

15-
1. Make sure your `gopls` is [up to date](user.md#installing).
16-
1. Check the [known issues](status.md#known-issues).
17-
1. [Report the issue](#file-an-issue).
11+
1. Verify that your project is in good shape by working with it outside of your editor. Running a command like `go build ./...` in the workspace directory will compile everything. For modules, `go mod tidy` is another good check, though it may modify your `go.mod`.
12+
1. Check that your editor isn't showing any diagnostics that indicate a problem with your workspace. They may appear as diagnostics on a Go file's package declaration, diagnostics in a go.mod file, or as a status or progress message. Problems in the workspace configuration can cause many different symptoms. See the [workspace setup instructions](workspace.md) for help.
13+
1. Make sure `gopls` is up to date by following the [installation instructions](user.md#installing), then [restarting gopls](#restart-gopls).
14+
1. Optionally, [ask for help](#ask-for-help) on Gophers Slack.
15+
1. Finally, [report the issue](#file-an-issue) to the `gopls` developers.
1816

19-
## File an issue
20-
21-
You can use:
22-
23-
* Your editor's bug submission integration (if available). For instance, `:GoReportGitHubIssue` in [`vim-go`](vim.md#vim-go).
24-
* `gopls bug` on the command line.
25-
* The [Go issue tracker](https://github.com/golang/go/issues/new?title=x%2Ftools%2Fgopls%3A%20%3Cfill%20this%20in%3E).
26-
27-
Along with an explanation of the issue, please share the information listed here:
28-
29-
1. Your editor and any settings you have configured (for example, your VSCode `settings.json` file).
30-
1. A sample program that reproduces the issue, if possible.
31-
1. The output of `gopls version` on the command line.
32-
1. The output of `gopls -rpc.trace -v check /path/to/file.go`.
33-
1. gopls logs from when the issue occurred, as well as a timestamp for when the issue began to occur. See the [instructions](#capturing-gopls-logs) for information on how to capture gopls logs.
17+
## Restart `gopls`
3418

35-
Much of this information is filled in for you if you use `gopls bug` to file the issue.
19+
`gopls` has no persistent state, so restarting it will fix transient problems. This is good and bad: good, because you can keep working, and bad, because you won't be able to debug the issue until it recurs.
3620

37-
### Capturing logs
21+
In most cases, closing all your open editors will guarantee that `gopls` is killed and restarted. If you don't want to do that, there may be an editor command you can use to restart only `gopls`. Note that some `vim` configurations keep the server alive for a while after the editor exits; you may need to explicitly kill `gopls` if you use `vim`.
3822

39-
#### VS Code
23+
## Ask for help
4024

41-
For VSCode users, the gopls log can be found by navigating to `View` -> `Output` (or `Ctrl+K Ctrl+H`). There will be a drop-down menu titled `Tasks` in the top-right corner. Select the `gopls (server)` item, which will contain the `gopls` logs.
25+
Gophers Slack has active editor-specific channels like [#emacs](https://gophers.slack.com/archives/C0HKHULEM), [#vim](https://gophers.slack.com/archives/C07GBR52P), and [#vscode](https://gophers.slack.com/archives/C2B4L99RS) that can help debug further. If you're confident the problem is with `gopls`, you can go straight to [#gopls](https://gophers.slack.com/archives/CJZH85XCZ). Invites are [available to everyone](https://invite.slack.golangbridge.org). Come prepared with a short description of the issue, and try to be available to answer questions for a while afterward.
4226

43-
To increase the level of detail in your logs, add the following to your VS Code settings:
44-
45-
```json5
46-
"go.languageServerFlags": [
47-
"-rpc.trace"
48-
]
49-
```
27+
## File an issue
5028

51-
To start a debug server that will allow you to see profiles and memory usage, add the following to your VS Code settings:
29+
We can't diagnose a problem from just a description. When filing an issue, please include as much as possible of the following information:
5230

53-
```json5
54-
"go.languageServerFlags": [
55-
"serve",
56-
"-rpc.trace",
57-
"--debug=localhost:6060",
58-
],
59-
```
31+
1. Your editor and any settings you have configured (for example, your VSCode `settings.json` file).
32+
1. A sample program that reproduces the issue, if possible.
33+
1. The output of `gopls version` on the command line.
34+
1. A complete gopls log file from a session where the issue occurred. It should have a `go env for <workspace folder>` log line near the beginning. It's also helpful to tell us the timestamp the problem occurred, so we can find it the log. See the [instructions](#capture-logs) for information on how to capture gopls logs.
6035

61-
You will then be able to view debug information by navigating to `localhost:6060`.
36+
Your editor may have a command that fills out some of the necessary information, such as `:GoReportGitHubIssue` in `vim-go`. Otherwise, you can use `gopls bug` on the command line. If neither of those work you can start from scratch directly on the [Go issue tracker](https://github.com/golang/go/issues/new?title=x%2Ftools%2Fgopls%3A%20%3Cfill%20this%20in%3E).
6237

63-
#### Other editors
38+
## Capture logs
6439

65-
For other editors, you may have to directly pass a `-logfile` flag to gopls.
40+
You may have to change your editor's configuration to pass a `-logfile` flag to gopls.
6641

6742
To increase the level of detail in your logs, start `gopls` with the `-rpc.trace` flag. To start a debug server that will allow you to see profiles and memory usage, start `gopls` with `serve --debug=localhost:6060`. You will then be able to view debug information by navigating to `localhost:6060`.
6843

6944
If you are unsure of how to pass a flag to `gopls` through your editor, please see the [documentation for your editor](user.md#editors).
7045

71-
### Restart your editor
72-
73-
Once you have filed an issue, you can then try to restart your `gopls` instance by restarting your editor. In many cases, this will correct the problem. In VSCode, the easiest way to restart the language server is by opening the command palette (Ctrl + Shift + P) and selecting `"Go: Restart Language Server"`. You can also reload the VSCode instance by selecting `"Developer: Reload Window"`.
74-
75-
## Memory usage
46+
## Debug memory usage
7647

77-
`gopls` automatically writes out memory debug information when your usage
78-
exceeds 1GB. This information can be found in your temporary directory with
79-
names like `gopls.1234-5GiB-withnames.zip`. On Windows, your temporary
80-
directory will be located at `%TMP%`, and on Unixes, it will be `$TMPDIR`,
81-
which is usually `/tmp`. Please create a
82-
[new issue](https://github.com/golang/go/issues/new?title=x%2Ftools%2Fgopls%3A%20%3Cfill%20this%20in%3E)
83-
with your editor settings and memory debug information attached. If you are
84-
uncomfortable sharing the package names of your code, you can share the
85-
`-nonames` zip instead.
48+
`gopls` automatically writes out memory debug information when your usage exceeds 1GB. This information can be found in your temporary directory with names like `gopls.1234-5GiB-withnames.zip`. On Windows, your temporary directory will be located at `%TMP%`, and on Unixes, it will be `$TMPDIR`, which is usually `/tmp`. Please [file an issue](#file-an-issue) with this memory debug information attached. If you are uncomfortable sharing the package names of your code, you can share the `-nonames` zip instead, but it's much less useful.

0 commit comments

Comments
 (0)