docs: rewrite troubleshooting guide
The troubleshooting guide had gotten quite long, and included things
like indentation settings that aren't really troubleshooting steps. With
gopls being on by default in the near future, it's a good time to
overhaul it.
I tried to cut down and streamline the content so that it's a little
less intimidating than it used to be. I deliberately erred on the side
of removing things, because it's easier to know that's something missing
than that something's unnecessary. That said, I don't do a lot of
support for vscode-go, so I may be miscalibrated on what's important.
Hopefully it's not too gopls-centric.
A nit: I noticed along the way formatting of the Locate Configured Go
Tools command could use some cleanup; it's not clear what's what. And
it would be very nice if that command showed more of the things needed
for a bug report.
Change-Id: Id1b2ee8b7807e4c1c451fd8e477f932d69b3027f
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/284587
Trust: Heschi Kreinick <heschi@google.com>
Trust: Hyang-Ah Hana Kim <hyangah@gmail.com>
Reviewed-by: Hyang-Ah Hana Kim <hyangah@gmail.com>
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 3b111af..d4824e2 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -1,241 +1,69 @@
# Troubleshooting
-Read this document when you encounter a problem with this extension. It can provide guidance, but many cases are not covered here.
+If you suspect that the Go extension is not working correctly, please follow the troubleshooting steps below.
-If you are unable to resolve the problem after following the advice on this page, please take a look at the current [open issues](https://github.com/golang/vscode-go/issues) to see if your issue has already been reported. If not, please do not hesitate to [ask for help](#ask-for-help).
+**NOTE: [Debugging](debugging.md#troubleshooting) has its own troubleshooting documentation.**
-**NOTE: [Debugging](debugging.md#troubleshooting) and [`gopls`](gopls.md) also have their own troubleshooting documentation.**
+## Make sure your project compiles
-## Overview
+Verify that your project is in good shape by working with it at the command line. 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`.
-* [Check known issues](#check-known-issues)
-* [Check your setup](#check-your-setup)
- * [Environment variables](#environment-variables)
-* [Update tools](#update-tools)
- * [If tools fail to install or update](#if-tools-fail-to-install-or-update)
-* [Look for error messages](#look-for-error-messages)
-* [Investigate](#investigate)
- * [Debugging](debugging.md#troubleshooting)
- * [Language server](gopls.md)
- * [Autocompletion](#autocompletion)
- * [Formatting](#formatting)
- * [Diagnostics](#diagnostics)
-* [Known Issues](#known-issues)
-* [Ask for help](#ask-for-help)
+## Look for serious errors and diagnostics
-### Check [known issues](#known-issues)
+Check that there aren't any diagnostics that indicate a problem with your workspace. First, check the bottom-center of the VS Code window for any errors. After that, check the package declaration of the any Go files you're working in, and your `go.mod` file. Problems in the workspace configuration can cause many different symptoms. See the [`gopls` workspace setup instructions](https://github.com/golang/tools/blob/master/gopls/doc/workspace.md) for help.
-A [list of known issues](#known-issues) is available at the bottom of this page. Take a look and see if you've encountered one of these.
+## Check your extension setup
-### Check your setup
+Run the [`Go: Locate Configured Go Tools`](commands.md#go-locate-configured-go-tools) command. The output is split into sections.
-First, make sure you understand the difference between [`GOPATH`](gopath.md) and [module](modules.md) modes and know which mode you are using. Run `go version` and `go env` in the [integrated terminal] to check that your environment is configured as you expect.
+In the first indented section, check that at least `gopkgs`, `go-outline`, `dlv`, and `gopls` are installed -- they're necessary for the extension's basic functionality. The other tools [provide optional features](tools.md) and are less important unless you need those features. You can install tools by running the [`Go: Install/Update Tools`](commands.md#go-installupdate-tools) command.
-This extension supports a few meta-commands that can be used for investigation. Try running [`Go: Locate Configured Go Tools`](commands.md#go-locate-configured-go-tools). The output should look like:
+Then, look at the `Workspace Folder` section(s) for the environment in use. Verify that `GOROOT` is set to a valid Go installation; if not, follow the [getting started guide](../README.md#install-go). If `GOPATH` is unset, or surprising, read more about [setting up your `GOPATH`](gopath.md#setting-gopath). Also, `GOMOD` should usually point to your project's `go.mod` file if you're in module mode. (More complicated workspace setups may have a blank `GOMOD`. See the `gopls` [workspace documentation](https://github.com/golang/tools/blob/master/gopls/doc/workspace.md) for more on valid workspace setups.) To change the workspace environment, use settings such as [`go.gopath`](settings.md#go.gopath) and [`go.toolsEnvVars`](settings.md#go.toolsEnvVars).
-```bash
-Checking configured tools....
-GOBIN: undefined
-toolsGopath:
-gopath: /path/to/gopath
-GOROOT: /path/to/go
-PATH: /path/to/:/another/path:/some/path
+Finally, take a look at your settings in the JSON form (`Preferences: Open Settings (JSON)`). This is an easier way to quickly see what non-default configurations you have. Consider [reading about](settings.md) any settings you don't understand, or just commenting them out.
- gocode: /path/to/gocode installed
- gopkgs: /path/to/bin/gopkgs installed
- go-outline: /path/to/bin/go-outline installed
- go-symbols: /path/to/bin/go-symbols installed
- guru: /path/to/bin/guru installed
- gorename: /path/to/bin/gorename installed
- gotests: /path/to/bin/gotests installed
- gomodifytags: /path/to/bin/gomodifytags installed
- impl: /path/to/bin/impl installed
- fillstruct: /path/to/bin/fillstruct installed
- goplay: /path/to/bin/goplay installed
- godoctor: /path/to/bin/godoctor installed
- dlv: /path/to/bin/dlv installed
- gocode-gomod: /path/to/bin/gocode-gomod installed
- godef: /path/to/bin/godef installed
- goreturns: /path/to/bin/goreturns installed
- golint: /path/to/bin/golint installed
- gopls: /path/to/bin/gopls installed
-```
+## Update tools
-If your `GOPATH` or `GOROOT` is undefined, that may indicate a problem. Read more about [setting up your `GOPATH`](gopath.md#setting-gopath). A missing `GOROOT` means that you haven't installed Go correctly. This topic is covered in the [getting started guide](../README.md#install-go).
+It's possible that you are using an outdated version of a tool, so the bug you are encountering may have already been fixed. You can update all tools at once by running the [`Go: Install/Update Tools`](commands.md#go-installupdate-tools) command.
-If one of the tools (`gocode`, `gopkgs`, etc.) is not installed, this may also indicate a problem. Take a look at the [list of tools](tools.md) required by this extension. If the missing tool provides the feature you're looking for, that might be the issue. You can install or update tools by running the [`Go: Install/Update Tools`](commands.md#go-installupdate-tools) command.
+## Restart `gopls`
-Finally, take a look at your settings in the JSON form (Ctrl+Shift+P -> Preferences: Open Settings (JSON)). This is an easier way to quickly grasp what non-default configurations you have.
+Many of the extension's features are provided by [`gopls`](https://golang.org/s/gopls), the official language server for Go. `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. You can restart `gopls` using the `Go: Restart Language Server` command.
-Common culprits include:
+## Ask for help
-* [`go.inferGopath`](settings.md#go.inferGopath)
-* [`go.toolsGopath`](settings.md#go.toolsGopath)
-* [`go.alternateTools`](settings.md#go.alternateTools)
-* [`go.useLanguageServer`](settings.md#go.useLanguageServer)
+After you've done the basic steps above, it's a good time to ask for help. Gophers Slack has a channel for [#vscode](https://gophers.slack.com/archives/C2B4L99RS) that can help debug further. If you're confident the problem is with `gopls`, you can go 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.
-Read up on those settings, as well as all of the other [available settings](settings.md).
+## Collect extension logs
-If you are using the language server, please see the language server's [troubleshooting guide](gopls.md).
-
-#### Environment variables
-
-Note that extensions run in a separate process from the [integrated terminal] and the rest of the VS Code window. Therefore, environment variables set specifically in the [integrated terminal] are not visible to the extensions.
-
-Instead, set the environment variables in your terminal before you launch VS Code. Or, set environment variables globally in your configuration (in a `.bash_profile`, for example). You can also set environment variables for only the Go extension by adding them to [`go.toolsEnvVars`](settings.md#go.toolsEnvVars). Other settings are available to override specific variables, like your `GOPATH`, which can be set through the [`go.gopath`](settings.md#go.gopath) setting as well.
-
-### Look for error messages
-
-Start off by opening the Output pane (Ctrl+Shift+U). On the right side, open the drop-down titled "Tasks". Any item that starts with "Go" is related to this extension. Browse through these output channels and make note of any error messages.
+Start off by opening the `View` -> `Output` pane. On the right side, open the drop-down titled "Tasks". Any item that starts with "Go" is related to this extension. Browse through these output channels and make note of any error messages.
You can also look directly in the logs of the Extension Host by selecting `Log (Extension Host)`. These may contain a lot of unrelated information, but they may prove useful. If you are trying to get the logs for a specific operation, like go to definition, clear the logs (Clear Output button on the right side), and perform the operation.
Errors may also be logged to the Developer Tools console. These errors may be more difficult to parse, but you can take a look at them by running the `Developer: Toggle Developer Tools` command from the Command Palette (Ctrl+Shift+P).
-### Update tools
+## Collect `gopls` information
-It's possible that you are using an outdated version of a tool, so the bug you are encountering may have already been fixed. You can update all tools at once by running the [`Go: Install/Update Tools`](commands.md#go-installupdate-tools) command.
+The gopls log can be found by navigating to `View` -> `Output`. 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.
-If you would prefer to update only a single tool, you can use the same command, but pick the correct tool. To learn which tool corresponds to the broken feature, read the [Features](features.md) and [Tools](tools.md) documentation pages. [Features](features.md) describes functionality in detail and lists which tool provides that functionality, while [Tools](tools.md) is the reverse, describing each tool and then listing which features it provides.
-
-### If tools fail to install or update
-
-It's possible that the tool installation or update will itself fail. Error messages should be printed in the output, which will hopefully guide you.
-
-Try cleaning your module cache (`go clean -modcache`) and installing once again.
-
-If you are using Go 1.10 or below, something may have gone wrong with the repository that contains the tool on your machine. Try deleting the directory that contains the tool and installing again. The directory will be in your `$GOPATH/src/`. The name of the directory will be the name of the repository in which the tool is hosted; it's usually something like `github.com/stamblerre/gocode`. Note that, if you have configured the [`go.toolsGopath`](settings.md#go.toolsGopath), you should look in that directory.
-
-If that doesn't work, there may be a problem with the tool itself. Check if there are any issues filed in the tool's repository. If not, please file an issue in that repository and let us know by [filing an issue](https:/github.com/golang/vscode-go/issues/new/choose) in the VS Code Go repository as well.
-
-## Investigate
-
-Issues in certain parts of the extension, specifically [debugging](debugging.md#troubleshooting) and the [language server](gopls.md), are described in more depth on other pages. Please take a look at those specific guides.
-
-Other issues may be caused by other command-line tools. As mentioned above, to learn which tool corresponds to the broken feature, read the [Features](features.md) and [Tools](tools.md) documentation pages. [Features](features.md) describes functionality in detail and lists which tool provides that functionality, while [Tools](tools.md) is the reverse, describing each tool and then listing which features it provides.
-
-Once you've identified the correct tool, make sure it works for you on the command-line. Read the documentation and usage guide for the tool and try running it manually. Most tools may require you to provide a line and column number or byte offset in a file.
-
-If the tool works correctly on the command-line, then the issue is in this extension. In that case, please [file an issue].
-
-If the tool does not work correctly on the command-line, that means there is an issue in the tool. In that case, please file an issue in the GitHub repository of the tool itself.
-
-### Autocompletion
-
-Autocompletion is one of the most complicated features. Troubleshooting it can be tricky, but doable.
-
-The following only applies if you are **not** using the language server. If you are, see [the `gopls` troubleshooting guide](gopls.md).
-
-The tool that provides autocompletion is called [`gocode`](tools.md#gocode), so try checking error logs and updating [`gocode`](tools.md#gocode). If you are using [Go modules], the binary on your machine will be called `gocode-gomod`, not `gocode`, as the extension uses a different version of `gocode` for modules.
-
-Next, make sure that the package you are trying to complete has been built at least once. You can do this by either running [`Go: Build Current Package`](commands.md#go-build-current-package) or by running `go install` on the command-line. If you have enabled [`go.buildOnSave`](settings.md#go.buildOnSave) or [`go.gocodeAutobuild`](settings.md#go.gocodeAutobuild), this should happen automatically.
-
-If you have noticed that your autocompletion results are not missing, but simply out-of date, check the value of your [`"go.buildOnSave"`](settings.md#buildOnSave) setting. If it is `"off"`, then you may not get fresh results your dependencies. You can rebuild your dependencies manually by running `go install`.
-
-If that doesn't work, try running `gocode close` on the command-line. If you are using [Go modules], run `gocode-gomod close`.
-
-Finally, try exiting VS Code Go and running:
-
-```bash
-gocode close
-gocode -s -debug
-```
-
-This will start a `gocode` debug server, which will print output as you trigger completions. Reopen VS Code and try to complete. You can trigger completion manually using Ctrl+Space. Make note of the debug output. If you can determine the issue from the output, you can correct it yourself. Otherwise, please [file an issue] and include this output in your report, if you are able to do so.
-
-### Formatting
-
-By default, this extension formats your code and organizes your imports on file save. New imports will be added and unused imports will be removed automatically. This is [standard Go style](https://golang.org/cmd/gofmt/). Learn more about the different [formatting tools](tools.md#formatting) to get a better understanding.
-
-If necessary, it is possible to disable the formatting behaviors. You will still be able to trigger formatting manually (right-click, Format Document).
-
-#### Disable formatting
-
-If you are **NOT using the language server** (`"go.useLanguageServer": false`, which is the default):
-
-* Format on save, but **do not** organize imports on save:
-
- ```json5
- "go.formatTool": "gofmt"
- ```
-
-* Do not format or organize imports on save:
-
- ```json5
- "[go]": {
- "editor.formatOnSave": false
- }
- ```
-
-If you **are using the language server** (`"go.useLanguageServer": true`):
-
-* Format on save, but **do not** organize imports on save:
-
- ```json5
- "[go]": {
- "editor.codeActionsOnSave": {
- "source.organizeImports": false
- }
- }
- ```
-
-* Do not format or organize imports on save:
-
- ```json5
- "[go]": {
- "editor.formatOnSave": false,
- "editor.codeActionsOnSave": {
- "source.organizeImports": false
- }
- }
- ```
-
-Learn more in the [language server documentation](gopls.md).
-
-#### Use spaces instead of tabs
-
-The default Go formatting tools use tabs over spaces, and this have become an industry standard for Go. Read more about [Effective Go](https://golang.org/doc/effective_go.html#formatting). The only way to switch from tabs to spaces is by also disabling formatting.
-
-#### Change tab size
-
-The default tab size in VS Code is 4. You can change this only for Go files by adding the following to your settings.
+To increase the level of detail in your logs, add the following to your settings:
```json5
-"[go]": {
- "editor.tabSize": 8
-}
+"go.languageServerFlags": [
+ "-rpc.trace"
+]
```
-### Diagnostics
+## File an issue
-This extension provides a number of [diagnostic features](features.md#diagnostics) to improve your code quality and alert you to build errors. These will appear as red or yellow squiggly underlines, and they will also appear in the Problems pane at the bottom of the screen. Learn more about the different [diagnostic tools](tools.md#diagnostics) to understand which ones you are using.
+We can't diagnose a problem from just a description. When filing an issue, please include as much as possible of the following information:
-#### Build errors
+1. Your Go version: `go -version`
+1. Your `gopls` version: `gopls -v version`
+1. Your vscode version: `code -v`
+1. Your Go extension version: `Extensions: Show Installed Extensions`
+1. Your Go environment: `go env` in the workspace folder
+1. Relevant VS Code settings: run `Preferences: Open Settings (JSON)` and include anything in a `[go]` block, and anything that starts with `go.` or `gopls.`
+1. Extension and `gopls` logs as seems appropriate for the bug.
-Any errors marked by red squiggles are build errors. These indicate that your code will not compile. If you think these errors are incorrect, try checking on the command-line by running `go build` or `go test`.
-
-If the build commands succeed, try copying the exact command used by VS Code Go. You can find it by navigating to the output pane (Ctrl+Shift+P -> `View: Toggle Output`). Choose the `Go` output channel from the Tasks drop-down in the top-right corner. This will show the exact command VS Code ran. Copy and run it.
-
-If you see the same errors, you may have misconfigured your project. Learn more about how to do this correctly in [set up your environment](../README.md#set-up-your-environment).
-
-If the command runs fine on the command-line, it's possible you've misconfigured something in your VS Code Go environment, such as your [`GOPATH`](gopath.md). Review [check your set-up](#check-your-set-up), and if the issue still persists, please [file an issue].
-
-## Ask for help
-
-It's possible that after following these steps, you still will not have found a solution to your problem. In this case, please ask for help!
-
-Reach out to the VS Code Go maintainers by:
-
-* [Filing an issue](https://github.com/golang/vscode-go/issues/new/choose)
-* Asking a question on the `#vscode` channel of the [Gophers Slack]
-
-## Known Issues
-
-**I keep seeing a "Running save participants..." pop-up when I save my file.**
-
-Take a look at the suggestions on [Microsoft/vscode-go#3179](https://github.com/microsoft/vscode-go/issues/3179#issue-600430641). If you still cannot resolve the problem, please [file an issue].
-
-[Gophers Slack]: https://gophers.slack.com/
-[file an issue]: https://github.com/golang/vscode-go/issues/new/choose
-[Go modules]: https://blog.golang.org/using-go-modules
-[integrated terminal]: https://code.visualstudio.com/docs/editor/integrated-terminal
+Once you've collected that information, [file your issue](https://github.com/golang/vscode-go/issues/new/choose).
\ No newline at end of file
