docs: update troubleshooting documentation
Update a few broken links and create a comprehensive troubleshooting
guide. Still needs more detail, particularly since the gopls, modules,
and GOPATH documentation is still missing.
I'd love to delete the FAQ entirely -- anything worth saying
should already be in the documentation, so the information should just
be made more accessible. I tried to delete as much as possible, but some
leftovers will still have to be cleaned up in follow-up CLs. I'll
convert that section to "Known issues" which is more helpful.
Change-Id: Ie7073f9548cdbfe34af42f04d9ce5136eb1070b7
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/236757
Reviewed-by: Hyang-Ah Hana Kim <hyangah@gmail.com>
diff --git a/.vscode/launch.json b/.vscode/launch.json
index ac1e019..49e3b5e 100644
--- a/.vscode/launch.json
+++ b/.vscode/launch.json
@@ -88,7 +88,7 @@
"${workspaceFolder}/out/test/unit"
],
"internalConsoleOptions": "openOnSessionStart"
- }
+ },
],
"compounds": [
{
diff --git a/README.md b/README.md
index 203a3ee..ba4578d 100644
--- a/README.md
+++ b/README.md
@@ -13,18 +13,17 @@
## Overview
* [Getting started](#getting-started)
+* [Support for Go modules](#support-for-go-modules)
* [Features](#features)
* [Debugging](#debugging)
* [Customization](#customization)
* [Linter](#linter)
* [GOPATH](#gopath)
-* [Language Server](#language-server)
+* [Language server](#language-server)
* [Troubleshooting](docs/troubleshooting.md)
-* [Frequently Asked Questions (FAQ)](docs/faq.md)
-* [Resources](#resources)
+* [Ask for help](#ask-for-help)
+* [Preview version](#preview-version)
* [Contributing](#contributing)
-* [Code of Conduct](#code-of-conduct)
-* [License](#license)
## Getting started
@@ -46,6 +45,8 @@
**NOTE: If you are using modules, we recommend using the Go [language server](#language-server), which is explained below.**
+More advanced users may be interested in using different `GOPATH`s or Go versions per-project. You can learn about the different `GOPATH` manipulation options in the [`GOPATH` documentation](gopath.md). Take a look at the other [customization](#customization) options as well.
+
### Install the extension
If you haven't already done so, install and open [Visual Studio Code](https://code.visualstudio.com). Navigate to the Extensions pane (Ctrl+Shift+X). Search for "Go" and install this extension (the publisher ID is "golang.Go").
@@ -56,11 +57,19 @@
You should immediately see a prompt in the bottom-right corner of your screen titled `Analysis Tools Missing`. This extension relies on a suite of [command-line tools](docs/tools.md), which must be installed separately from the extension. Accept the prompt, or use the `Go: Install/Update Tools` command to pick which tools you would like to install. Note that you must have [`git`](https://git-scm.com/) installed.
+If you see an error that looks like `command Go: Install/Update Tools not found`, it means that the extension has failed to activate and register its commands. Please uninstall and then reinstall the extension.
+
### Start coding
You're ready to Go!
-Be sure to learn more about the many [features](#features) of this extension, as well as how to [customize](#customization) them. See [Troubleshooting](docs/troubleshooting.md), [FAQ](docs/faq.md), and [Resources](#resources) for further guidance.
+Be sure to learn more about the many [features](#features) of this extension, as well as how to [customize](#customization) them. Take a look at [Troubleshooting](docs/troubleshooting.md) and [Resources](#resources) for further guidance.
+
+## Support for Go modules
+
+[Go modules](https://blog.golang.org/using-go-modules) have added a lot of complexity to the way most tools and features are built for Go. This has also added a lot of latency to most of the features. Some, but not all, [features](features.md) of this extension have been updated to work with Go modules. Some features may be slower in module mode. The [features documentation](features.md) contains more specific details.
+
+**In general, we recommend using [gopls, the official Go language server](#language-server), if you are using modules.** Read more [below](#language-server) and in the [gopls](gopls.md) documentation.
## [Features](docs/features.md)
@@ -104,12 +113,16 @@
For more information, see the [`gopls` documentation](docs/gopls.md).
-## Resources
+## Ask for help
If you're having issues with this extension, please reach out to us by [filing an issue](https://github.com/golang/vscode-go/issues/new/choose) or asking a question on the [Gophers Slack]. We hang out in the `#vscode` channel!
Take a look at [learn.go.dev](https://learn.go.dev) and [golang.org/help](https://golang.org/help) for additional guidance.
+## [Preview version](nightly.md)
+
+If you'd like to get early access to new features and bug fixes, you can use the nightly build of this extension. Learn how to install it in by reading the [Go Nightly documentation](nightly.md).
+
## [Contributing](docs/contributing.md)
We welcome your contributions and thank you for working to improve the Go development experience in VS Code. If you would like to help work on the VS Code Go extension, please see our [Contribution guide](docs/contributing.md). It explains how to build and run the extension locally, as well as the process of sending a contribution.
@@ -118,7 +131,7 @@
This project follows the [Go Community Code of Conduct](https://golang.org/conduct). If you encounter an issue, please mail conduct@golang.org.
-## License
+## [License](LICENSE)
[MIT](LICENSE)
diff --git a/docs/contributing.md b/docs/contributing.md
index 4008f94..1e93e7a 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -6,11 +6,13 @@
* [Before you start coding](#before-you-start-coding)
* [Ask for help](#ask-for-help)
+ * [Debug Adapter](#debug-adapter)
* [Developing](#developing)
* [Setup](#setup)
* [Run](#run)
* [Test](#test)
* [Sideload](#sideload)
+
* [Mail your change for review](#mail-your-change-for-review)
## Before you start coding
@@ -23,12 +25,16 @@
The VS Code Go maintainers are reachable via the issue tracker and the [#vscode-dev] channel on the [Gophers Slack]. Please reach out on Slack with questions, suggestions, or ideas. If you have trouble getting started on an issue, we'd be happy to give pointers and advice.
+### Debug Adapter
+
+Please note that extra configuration is required to build and run the [Debug Adapter](debug-adapter.md), which controls the debugging features of this extension. Refer to [the documentation for the Debug Adapter](debug-adapter.md) to set that up.
+
## Developing
### Setup
1) Install [node](https://nodejs.org/en/).
-2) Clone the repository, run `npm install` and open VS Code:
+2) Clone the repository, run `npm install`, and open VS Code:
```bash
git clone https://github.com/golang/vscode-go
@@ -37,8 +43,8 @@
code .
```
-3) Make sure the `window.ope
-nFoldersInNewWindow` setting is not `"on"`. <!--TODO(rstambler): Confirm that this is still required.-->
+3) Make sure the `window.openFoldersInNewWindow` setting is not `"on"`.
+<!--TODO(rstambler): Confirm that this is still required.-->
### Run
@@ -50,8 +56,6 @@
If you make further edits in the codebase, you can reload (`Ctrl+R`) the `[Extension Development Host]` instance of VS Code, which will load the new code. The debugging instance will automatically reattach.
-To debug the Go debugger, see the [debugAdapter README](../src/debugAdapter/README.md).
-
## Test
There are currently three test launch configurations: (1) Launch Extension Tests, (2) Launch Extension Tests with Gopls, and (3) Launch Unit Tests. To run the tests locally, open the Run view (`Ctrl+Shift+D`), select the relevant launch configuration, and hit the Play button (`F5`).
diff --git a/docs/debug-adapter.md b/docs/debug-adapter.md
new file mode 100644
index 0000000..26cd49c
--- /dev/null
+++ b/docs/debug-adapter.md
@@ -0,0 +1,60 @@
+# Debug Adapter
+
+The [Debug Adapter](../src/debugAdapter) runs in a separate Node.js process, which is spawned by VS Code when you debug Go code.
+
+Please see the [Debug Adapter Protocol (DAP)](https://microsoft.github.io/debug-adapter-protocol/) to understand how the Debug Adapter acts as an intermediary between VS Code and the debugger ([Delve](https://github.com/go-delve/delve)).
+
+This codebase is currently in flux: We are working on using's [`Delve`'s native DAP implementation](https://github.com/go-delve/delve/tree/master/service/dap) instead of this one. Follow along with [golang/vscode-go#23](https://github.com/golang/vscode-go/issues/23) for updates on that work.
+
+## Overview
+
+* [Before you begin](#before-you-begin)
+* [Debug only the Debug Adapter](#debug-only-the-debug-adapter)
+* [Debug the VS Code extension and the Debug Adapter](#debug-the-entire-extension-including-the-debug-adapter)
+* [Debug VS Code and the Debug Adapter](#debug-vs-code-and-the-debug-adapter)
+
+## Before you begin
+
+Before you start working on your change, please read the [Contribution guidelines](contributing.md). This document assumes that you are already familiar with the process of [building](contributing.md#build), [running](contributing.md#run), and [sideloading](contributing.md#sideload) the VS Code Go extension.
+
+## Debug only the Debug Adapter
+
+As a next step, you may want to debug the Debug Adapter, in order to understand how your change work with [`Delve`](tools.md#delve).
+
+**NOTE: Since the Debug Adapter runs in a separate process from the rest of the extension, the steps below only enable you to debug the Debug Adapter code, not the entire extension. To debug the entire extension, as well as the debug adapter, see the instructions [below](#debug-the-entire-extension).**
+
+1. Open the `vscode-go` folder in VS Code.
+2. Go the Run view and choose the `Launch as server` debug configuration.
+3. Add breakpoints as needed to the [`vscode-go/src/debugAdapter/goDebug.ts`](../src/debugAdapter/goDebug.ts) file.
+4. Open another instance of VS Code and open the Go project to debug.
+5. Create a debug configuration for the Go project if it doesn't exist. Set `"debugServer": 4711` in the root of the configuration.
+6. Start debugging your Go program using this configuration. This will trigger the breakpoints in `goDebug.ts` file.
+
+## Debug the entire extension, including the Debug Adapter
+
+You should take this step if your change modifies both the Debug Adapter and the main extension. This setup requires three instances of VS Code.
+
+1. Open the root [`vscode-go`](../) folder in one instance of VS Code.
+2. Choose the `Launch Extension` debug target and run it (F5). This will launch the second instance of VS Code.
+3. In this second instance, open the Go application you'd like to debug. Here, as above, create a debug configuration pointing to the program you want to debug. Add `"debugServer": 4711` to the root of the configuration.
+4. Open a third instance of VS Code an the [`vscode-go/src/debugAdapter`](../src/debugAdapter) folder. In this instance, select the `Launch as server` configuration and run it (F5).
+5. Return to the second VS Code instance with the Go program. Run the debug configuration (F5). Debuggers from the other two VS Code windows are attached to the Go debug adapter and the Go language integration respectively, so you can set breakpoints, step through code and inspect state as needed.
+
+<!--TODO(rstambler): Do we need to delete the src/debugAdapter/.vscode/launch.json file?-->
+
+## Debug VS Code and the Debug Adapter
+
+In some very rare cases, you may find it helpful to debug VS Code itself. Examples of such cases include veryfing workbench behavior and state before executing debug adapter API calls.
+
+First, ensure that you can [build and run VS Code](https://github.com/Microsoft/vscode/wiki/How-to-Contribute#build-and-run) from source successfully.
+
+Next, follow these steps:
+
+1. Open an instance of VS Code, which you have built from source.
+2. [Sideload](contributing.md#sideload) your local `vscode-go` extension to the local instance of VS. This can be done by copying the contents of the vscode-go folder into `$HOME/.vscode-oss-dev/extensions/ms-vscode.go` (the exact location may vary by OS).
+3. Open the `vscode` folder in Visual Studio Code.
+4. Launch the VS Code debug instance (OSS - Code) by choosing the `Launch VS Code` debug configuraion from the drop-down in the Run view. Add a breakpoints as needed.
+5. In another instance of VS Code, open the [`vscode-go`](../) folder. Choose the `Launch as server` debug configuration in the Run view. Add breakpoints as desired in the [`vscode-go/src/debugAdapter/goDebug.ts`](../src/debugAdapter/goDebug.ts) file.
+6. Open the Go application that you want to debug in the OSS Code instance initiated in step 4.
+7. Create a debug configuration with the setting `"debugServer": 4711` in the root.
+8. Start debugging your Go application. Observe that any breakpoints you set in the VS Code and debug adapter codebases will be triggered.
diff --git a/docs/debugging.md b/docs/debugging.md
index c9723ff..e50bbf6 100644
--- a/docs/debugging.md
+++ b/docs/debugging.md
@@ -15,7 +15,15 @@
* [Debugging on Windows Subsystem for Linux (WSL)](#debugging-on-windows-subsystem-for-linux-wsl)
* [Remote Debugging](#remote-debugging)
* [Troubleshooting](#troubleshooting)
- * [Common issues](#common-issues)
+ * [Read documentation and common issues](#read-documentation-and-common-issues)
+ * [Update Delve](#update-delve)
+ * [Check for multiple versions of Delve](#check-for-multiple-versions-of-delve)
+ * [Check your launch configuration](#check-your-launch-configuration)
+ * [Check your GOPATH](#check-your-gopath)
+ * [Enable logging](#enable-logging)
+ * [Optional: Debug the debugger](#optional-debug-the-debugger)
+ * [Ask for help](#ask-for-help)
+* [Common issues](#common-issues)
## Set up
@@ -269,13 +277,41 @@
The suggestions below are intended to help you troubleshoot any problems you encounter. If you are unable to resolve the issue, please take a look at the [current known debugging issues](https://github.com/golang/vscode-go/issues?q=is%3Aissue+is%3Aopen+label%3Adebug) or [file a new issue](https://github.com/golang/vscode-go/issues/new/choose).
+### Read documentation and [common issues](#common-issues)
+
+Start by taking a quick glance at the [common issues](#common-issues) described below. You can also check the [Delve FAQ](https://github.com/go-delve/delve/blob/master/Documentation/faq.md) in case the problem is mentioned there.
+
### Update Delve
-A good first step is to make sure that you are working with the latest version of Delve. You can do this by running the `Go: Install/Update Tools` command and selecting `dlv`.
+If the problem persists, it's time to start troubleshooting. A good first step is to make sure that you are working with the latest version of Delve. You can do this by running the `Go: Install/Update Tools` command and selecting `dlv`.
-### Read the Delve documentation
+### Check your [launch configuration](#launch-configurations)
-Take a quick glance at the [Delve FAQ](https://github.com/go-delve/delve/blob/master/Documentation/faq.md) in case the problem is mentioned there.
+Next, confirm that your [launch configuration](#launch-configurations) is correct.
+
+One common error is `could not launch process: stat ***/debug.test: no such file or directory`. You may see this while running in the `test` mode. This happens when the `program` attribute points to a folder with no test files, so ensure that the `program` attribute points to a directory containing the test files you wish to debug.
+
+Also, check the version of the Delve API used in your [launch configuration](#launch-configurations). This is handled by the `–api-version` flag, `2` is the default. If you are debugging on a remote machine, this is particularly important, as the versions on the local and remote machines much match. You can change the API version by editing the [configuration in the `launch.json` file](#launch-configurations).
+
+### Check for multiple versions of Delve
+
+You might have multiple different versions of `dlv` installed, and VS Code Go could be using a wrong or old version. Run the `Go: Locate Configured Go Tools` command and see where VS Code Go has found `dlv` on your machine. You can try running `which dlv` to see which version of `dlv` you are using on the [command-line](https://github.com/go-delve/delve/tree/master/Documentation/cli).
+
+To fix the issue, simply delete the version of `dlv` used by the Go extension. Note that the extension first searches for binaries in your `$GOPATH/bin` and then looks on your `$PATH`.
+
+<!--TODO(rstambler): It feels like we should just prefer whatever is on the PATH and fallback to GOPATH if it's not found?-->
+
+If you see the error message `Failed to continue: "Error: spawn EACCES"`, the issue is probably multiple versions of `dlv`.
+
+### Try building your binary **without** compiler optimizations
+
+If you notice `Unverified breakpoints` or missing variables, ensure that your binary was built **without** compiler optimizations. Try building the binary with the `-gcflags="all=-N -l"`.
+
+### Check your `GOPATH`
+
+Make sure that the debugger is using the right [`GOPATH`](gopath.md). This is probably the issue if you see `Cannot find package ".." in any of ... errors. Read more about configuring your [GOPATH](gopath.md) or [file an issue report](https://github.com/golang/vscode-go/issues/new/choose).
+
+**As a work-around**, add the correct `GOPATH` as an environment variable in the `env` property in the `launch.json` file.
### Enable logging
@@ -298,49 +334,25 @@
At this point, it's time to look at the [common issues](#common-issues) below or the [existing debugging issues](https://github.com/golang/vscode-go/issues?q=is%3Aissue+is%3Aopen+label%3Adebug) on the [issue tracker](https://github.com/golang/vscode-go/issues). If that still doesn't solve your problem, [file a new issue](https://github.com/golang/vscode-go/issues/new/choose) or ask a question on the `#vscode` channel of the [Gophers Slack](https://gophers.slack.com).
-### Common issues
+## Common Issues
-#### Unverified breakpoint or variables
-
-Ensure that the binary being debugged was built **without optimizations**. Build the binary with the flags `-gcflags="all=-N -l"`.
-
-#### Cannot find package ".." in any of ...
-
-The debugger is not using the right [`GOPATH`](gopath.md). [File an issue report](https://github.com/golang/vscode-go/issues/new/choose).
-
-**As a work-around**, add the correct `GOPATH` as an environment variable in the `env` property in the `launch.json` file.
-
-#### Failed to continue: "Error: spawn EACCES"
-
-You have `dlv` running just fine from command line, but VS Code gives this access-related error.
-
-This can happen if you have multiple versions of `dlv` installed; the extension may have found an old or incorrect version. The extension first searches for binaries in your `$GOPATH/bin` and then looks on your `$PATH`.
-
-**_Solution_**: Run `which dlv` in the command-line. If this does not resolve to the version of `dlv` in your `$GOPATH/bin`, simply delete the version of `dlv` in your `$GOPATH/bin`. (You can also copy this version of `dlv` to your `$GOPATH/bin`.)
-
-#### could not launch process: stat ***/debug.test: no such file or directory
-
-You may see this in the debug console while trying to run in the `test` mode. This happens when the `program` attribute points to a folder with no test files.
-
-**_Solution_**: Ensure that the `program` attribute points to the folder that contains the test files you want to run.
-
-#### delve/launch hangs with no messages on WSL
+### delve/launch hangs with no messages on WSL
Try running ```delve debug ./main``` in the WSL command line and see if you get a prompt.
-**_Solution_**: Ensure you are running the WSL 2 Kernel, which (as of 4/15/2020) requires an early release of the Windows 10 OS. This is available to anyone via the Windows Insider program. See [WSL 2 Installation](https://docs.microsoft.com/en-us/windows/wsl/wsl2-install)
+**_Solution_**: Ensure you are running the WSL 2 Kernel, which (as of 4/15/2020) requires an early release of the Windows 10 OS. This is available to anyone via the Windows Insider program. See [Debugging on WSL](#debugging-on-windows-subsystem-for-linux-wsl).
-#### could not launch process: could not fork/exec
+### could not launch process: could not fork/exec
The solution this issue differs based on your OS.
-##### OSX
+#### OSX
This usually happens on OSX due to signing issues. See the discussions in [Microsoft/vscode-go#717](https://github.com/Microsoft/vscode-go/issues/717), [Microsoft/vscode-go#269](https://github.com/Microsoft/vscode-go/issues/269) and [derekparker/delve#357](https://github.com/derekparker/delve/issues/357).
**_Solution_**: You may have to uninstall dlv and install it manually as described in the [Delve instructions](https://github.com/derekparker/delve/blob/master/Documentation/installation/osx/install.md#manual-install).
-##### Linux/Docker
+#### Linux/Docker
Docker has security settings preventing `ptrace(2)` operations by default within the container.
@@ -350,10 +362,6 @@
This error can show up for Mac users using Delve versions 0.12.2 and above. `xcode-select --install` has solved the problem for a number of users.
-#### Unverified breakpoints when remote debugging
-
-Check the version of the Delve API used in the remote Delve process by checking the value of the `–api-version` flag. This needs to match the version used by the Go extension (`2`, by default). You can change the API version by editing the configuration in the `launch.json file.
-
[Delve]: https://github.com/go-delve/delve
[VS Code variables]: https://code.visualstudio.com/docs/editor/variables-reference
-[snippets]: https://code.visualstudio.com/docs/editor/userdefinedsnippets
\ No newline at end of file
+[snippets]: https://code.visualstudio.com/docs/editor/userdefinedsnippets
diff --git a/docs/faq.md b/docs/faq.md
deleted file mode 100644
index 6369536..0000000
--- a/docs/faq.md
+++ /dev/null
@@ -1,127 +0,0 @@
-# Frequently Asked Questions
-
-**Q: I installed the plugin, but none of the features are working. Why?**
-
-**A:** Make sure to install all the dependent Go tools. Run `Go: Install/Update Tools`. If you want to install only selected tools, then go through the [Go tools that this plugin depends on](tools.md) and install the ones you need manually
-
-If you see an error of the form `command <command-name-here> not found`, it means that the extension has failed to activate and register its commands. Please try to uninstall and re-install the extension.
-
-**Q: I see "git pull --ff-only" errors when installing tools.**
-
-**A:** Chances are that there was a force pushed commit to the repo for the tool being installed. Delete the folder corresponding to this tool in your `$GOPATH/src` (if you have set `go.toolsGopath`, then check there) and try again.
-
-**Q: Why do my imported packages keep getting removed or re-ordered?**
-
-**A:** By default, the plugin formats your code and organizes your imports (add missing imports, remove unused imports, order imports) on each file save. You can disable this feature using settings.
-- If not using the `gopls` language server, then either add `"go.formatTool": "gofmt"` to your settings to choose a formatting tool that doesn't touch imports or disable the format on save feature entirely using the below
-```json
-"[go]": {
- "editor.formatOnSave": false
-}
-```
-- If you are using the `gopls` language server, then the organizing of imports is pulled out of the formatting process. To disable the organizing of imports in this case, add the below in your settings
-```
-"[go]": {
- "editor.codeActionsOnSave": {
- "source.organizeImports": false
- }
- }
-```
-
-**Q: Why do my spaces keep getting replaced with tabs when saving the file?**
-
-**A:** Because the formatting tools used by this extension either `goreturns`, `goimports` or `gofmt` or `gopls` all follow the default Go formatting rule of using tabs instead of spaces.
-
-**Q: Shouldn't the formatting tools be using a tab size of 8?**
-
-**A:** The default tab size in VS Code is 4. To change this to 8 for Go files, add the below to your settings.
-```json
-"[go]": {
- "editor.tabSize": 8
-}
-```
-
-**Q: How does the plugin determine the GOPATH to use?**
-
-**A:** See [GOPATH in the VS Code Go extension](gopath.md)
-
-**Q: Does VS Code support Go modules?**
-
-**A:** See [Go modules support in VS Code](modules.md)
-
-**Q: Why is code navigation and code completion slow when using Go modules?**
-
-Please see [Go modules support in VS Code](modules.md)
-
-**Q: Can I use language server when using Go modules?**
-
-**A:** Yes! Please see [Go language server in VS Code](https://github.com/Microsoft/vscode-go#go-language-server)
-
-**Q: How do I just run my code? Not debug, just run.**
-
-**A:** Use the keybinding `Ctrl+F5` or run the command `Debug: Start without Debugging`.
-
-Behind the scenes, we use `go run` command which takes a file path. Therefore, If you already have a `launch.json` file with default configuration, update it to use `${file}` instead of `${fileDirname}` instead. If you are using your own debug configuration, ensure that the `program` property needs to point to a file and not directory.
-
-In the absence of a file path in the `program` property, `Start without Debugging` falls back to normal debugging
-
-**Q: Why is the GOPATH I set in the integrated terminal not being used by the plugin? Why isn't my program getting the environment variables I set in the integrated terminal?**
-
-**A:** The extensions run in a separate process than the terminal or rest of the VS Code window. Therefore, environment variables set specifically in the integrated terminal is not visible to the extensions.
-
-**Q: Where do I see the logs from the extension?**
-
-**A:** In the `View` menu, select `Output` which will bring up the output panel. In the top right corner of this panel, select `Log (Extension Host)` from the drop down.
-_Tip_: If you are looking for logs after doing a particular operation, first clear the logs and try again to reduce the noise
-
-**Q: Auto-completions stopped working. What do I do?**
-- Check the logs for errors first. See the previous question on how to view logs from the extension.
-- If you are using the language server, then the dropdown for output pane in the previous step will have an entry for the language server (i.e., `gopls`). Check that out.
-- If you are **not** using the language server,
- - and this is for symbols from external packages, then ensure they installed first. You can do this by either running `Go: Build Current Package` which will install all dependencies or install the dependencies manually yourself using `go install`.
- - If it still doesnt work, run `gocode close` or `gocode exit` in a terminal and try again. Use `gocode-gomod` instead of `gocode` if you are using Go modules.
- - If it still doesnt work, run `Go: Install/Update Tools`, choose `gocode` to update the tool. Choose `gocode-gomod` if you are using Go modules
- - If it still doesnt work, run `gocode close` or `gocode exit` followed by `gocode -s -debug` in a terminal and try again. Results from `gocode` will show up in the terminal. Use `gocode-gomod` instead of `gocode` if you are using Go modules.
- - If you see expected results in the terminal, but not in VS Code, log an issue in the [vscode-go](https://github.com/Microsoft/vscode-go) repo, else
-log an issue in the [gocode](https://github.com/mdempsky/gocode) repo. If you are using Go modules, log the issue in https://github.com/stamblerre/gocode
-
-**Q: File saving is sometimes slow or stuck running save participants.**
-
-**A:** You may noticed this problem because of the window popup with a
-message such as "Running Save Participants ...". This indicates the
-underlying tools used for file formatting or other code action such as
-package imports take longer than desired. Before 1.42, VS Code aborted
-the code action and skipped formatting, which resulted in file saving
-without expected formatting or import. After 1.42, VS Code changed to
-surface the issue and let users either wait or cancel the entire file
-save operation.
-
-There are many reasons that cause the underlying tools to misbehave.
-Please file [an issue](https://github.com/microsoft/vscode-go/issues/new)
-with information about your settings and, if possible, with the workspace
-structure (e.g., where is the workspace directory relative to `GOPATH`,
-where is `go.mod`, in what directory you opened from the `code`, etc.).
-
-If you are using `gopls`, follow the
-[`gopls` troubleshooting documentation](https://github.com/golang/tools/blob/master/gopls/doc/troubleshooting.md)
-to capture gopls traces and include them in the issue.
-
-Workarounds such as 1) disabling "On Save" features, or 2) canceling the
-slow file saving operation and retrying to save file without formatting
-using "Alt+k, s" ("File: Save Without Formatting" command) exist but should
-be used as a last resort because this skips all the formatting and auto import
-features.
-
-**Q: My imports have red lines saying "package not found"**
-
-**A:** These are build errors. Go to View -> Output -> Select "Go" from the dropdown on the top right corner of the panel. Here you can see the output of the `go build` (or `go test` if the current file is a test file). Copy the `go build` command along with arguments and try running it in the terminal. If you still see the same errors, then the problem is in your setup of GOPATH. If it runs fine, then log an issue and we can look into it
-
-**Q: How do I get the features/bug fixes that are implemented but not released yet? How do I get the beta version of the Go extension?**
-
-**A:** Install the [Go Nightly](nightly.md) extension.
-
-**Q: I am seeing out-of-date completion results.**
-
-If you are using the language server (`"go.useLanguageServer": true`), please file a [`gopls` issue](https://github.com/golang/go/issues/new).
-
-Otherwise, check the value of `"go.buildOnSave"`. If it is `"off"`, then you may not get fresh results from not-yet-built dependencies. Therefore, ensure you have built your dependencies manually in such cases.
diff --git a/docs/features.md b/docs/features.md
index 61991e1..9c581c1 100644
--- a/docs/features.md
+++ b/docs/features.md
@@ -35,10 +35,11 @@
* [Build errors](#build-errors)
* [Vet errors](#vet-errors)
* [Lint errors](#lint-errors)
-* [Testing](#testing)
- * [Test and benchmark in the editor](#test-and-benchmark-in-the-editor)
+* [Run and test in the editor](#run-and-test-in-the-editor)
+ * [Run your code](#run-your-code)
+ * [Test and benchmark](#test-and-benchmark)
* [Code coverage](#code-coverage)
-* [Debugging](#debugging)
+* [Debug your code](#debug-your-code)
* [Other](#other)
* [Go Playground](#go-playground)
@@ -54,17 +55,17 @@
### Signature help
-Information about the signature of a function pops up as you type in its parameters. This feature is provided by the [`gogetdoc`](tools.md#gogetdoc) tool, but it can also be provided by a combination of [`godef`](tools.md#godef) and [`godoc`](tools.md#godoc) (configured via the [`"go.docsTool"`](commands.md#docs-tool) setting).
+Information about the signature of a function pops up as you type in its parameters. This feature is provided by the [`gogetdoc`](tools.md#gogetdoc) tool, but it can also be provided by a combination of [`godef`](tools.md#godef) and [`godoc`](tools.md#godoc) (configured via the [`"go.docsTool"`](settings.md#docsTool) setting).
### Quick info on hover
-Documentation appears when you hover over a symbol. This feature is provided by the [`gogetdoc`](tools.md#gogetdoc) tool, but it can also be provided by a combination of [`godef`](tools.md#godef) and [`godoc`](tools.md#godoc) (configured via the [`"go.docsTool"`](commands.md#docs-tool) setting).
+Documentation appears when you hover over a symbol. This feature is provided by the [`gogetdoc`](tools.md#gogetdoc) tool, but it can also be provided by a combination of [`godef`](tools.md#godef) and [`godoc`](tools.md#godoc) (configured via the [`"go.docsTool"`](settings.md#docsTool) setting).
## [Code Navigation](https://code.visualstudio.com/docs/editor/editingevolved)
### Go to definition
-Jump to or peek a symbol's declaration. This feature is provided by the [`gogetdoc`](tools.md#gogetdoc) tool, but it can also be provided by a combination of [`godef`](tools.md#godef) and [`godoc`](tools.md#godoc) (configured via the [`"go.docsTool"`](commands.md#docs-tool) setting).
+Jump to or peek a symbol's declaration. This feature is provided by the [`gogetdoc`](tools.md#gogetdoc) tool, but it can also be provided by a combination of [`godef`](tools.md#godef) and [`godoc`](tools.md#godoc) (configured via the [`"go.docsTool"`](settings.md#docsTool) setting).
### Find references
@@ -112,6 +113,8 @@
}
```
+If you're having issues with the formatting provided by this extension, take a look at the [Troubleshooting Formatting](troubleshooting.md#investigating-formatting) documentation.
+
#### Add import
Manually add a new import to your file through the `Go: Add Import` command. Available packages are offered from your `GOPATH` and module cache.
@@ -144,27 +147,37 @@
## Diagnostics
+Learn more about [diagnostic errors](tools.md#diagnostics).
+
### Build errors
-Build errors can be shown as you type or on save. Configure this behavior through the [`"go.buildOnSave"`](commands.md#buildOnSave) setting.
+Build errors can be shown as you type or on save. Configure this behavior through the [`"go.buildOnSave"`](settings.md#buildOnSave) setting.
By default, code is compiled using the `go` command (`go build`), but build errors as you type are provided by the [`gotype-live`](tools.md#gotype-live) tool.
### Vet errors
-Vet errors can be shown on save. The vet-on-save behavior can also be configured through the [`"go.vetOnSave"`](commands.md#vetOnSave) setting.
+Vet errors can be shown on save. The vet-on-save behavior can also be configured through the [`"go.vetOnSave"`](settings.md#vetOnSave) setting.
The vet tool used is the one provided by the `go` command: `go vet`.
### Lint errors
-Much like vet errors, lint errors can also be shown on save. This behavior is configurable through the [`"go.lintOnSave"`](commands.md#lintOnSave) setting.
+Much like vet errors, lint errors can also be shown on save. This behavior is configurable through the [`"go.lintOnSave"`](settings.md#lintOnSave) setting.
-The default lint tool is the one provided by the `go` command: `go lint`. However, custom lint tools can be easily used instead by configuring the [`"go.lintTool"`](commands.md#lintTool) setting. To learn more about the different options, see the [documentation for diagnostic tools](tools.md#diagnostics).
+The default lint tool is the one provided by the `go` command: `go lint`. However, custom lint tools can be easily used instead by configuring the [`"go.lintTool"`](settings.md#lintTool) setting. To learn more about the different options, see the [documentation for diagnostic tools](tools.md#diagnostics).
-## Testing
+## Run and test in the editor
-### Test and benchmark in the editor
+### Run your code
+
+To run your code without debugging, use the keyboard shortcut `Ctrl+F5` or run the command `Debug: Start without Debugging`. To debug, see [Debugging](#debugging) below.
+
+This command requires you to have a [launch configuration](#launch-configuration) in a `launch.json` file. To open or create your `launch.json`, run the `Debug: Open launch.json` command. Use the default `Go: Launch file` configuration.
+
+Behind the scenes, the `Debug: Start without Debugging` command calls `go run`. `go run` usually requires the path to the file to run, so your `launch.json` should contain `"program": "${file}"`.
+
+### Test and benchmark
[Code lenses](https://code.visualstudio.com/blogs/2017/02/12/code-lens-roundup) allow users to easily run tests and benchmarks for a given function, file, package, or workspace. Alternatively, the same functionality is available through a set of commands: `Go: Test Function At Cursor`, `Go: Test File`, `Go: Test Package`, and `Go: Test All Packages in Workspace`.
@@ -180,4 +193,4 @@
### Go Playground
-Quickly export your current file to the [Go Playground](https://play.golang.org) via the `Go: Run On Go Playground` command. This is useful for quickly exporting code for an example.
+Export your current file to the [Go Playground](https://play.golang.org) via the `Go: Run On Go Playground` command. This is useful for quickly exporting code for an example.
diff --git a/docs/on-save.md b/docs/on-save.md
deleted file mode 100644
index afaa85c..0000000
--- a/docs/on-save.md
+++ /dev/null
@@ -1,71 +0,0 @@
-The Go extension runs the below on each file save by default. You can turn them off in settings.
-* Build (Turn off using `go.buildOnSave` setting)
-* Lint (Turn off using `go.lintOnSave` setting)
-* Vet (Turn off using `go.vetOnSave` setting)
-* Format (Turn off by adding the below in your settings)
-```
-"[go]": {
- "editor.formatOnSave": false
-}
-
-```
-
-The below can be enabled to run on file save by turning them on in settings
-* Test
-* Code Coverage
-
-## Build on save
-
-On each file save, the package that the file belongs to is built to find any compile errors. If the file is a test file then `go test -i -c -o` is used instead of `go build -i -o`
-
-The binary generated by the build process is written to a temporary location as the purpose here is to only find compile errors and not to provide a binary/executable.
-
-The below settings control the build on save feature
-- go.buildOnSave
- - Use this to either turn off the build on save feature or enable it at package or workspace level
-- go.buildTags
- - The tags provided here is used by the build and vet processes as well as any other Go tool used by this extension that takes the `-tags` flag
-- go.buildFlags
- - Is used both by the build and test processes
-- go.installDependenciesWhenBuilding
- - By default, `-i` flag is passed to speed up the build process. If you don't want the `-i` flag to be used, set `go.installDependenciesWhenBuilding` to `false`.
-
-## Lint on save
-
-A linter is a tool giving coding style feedback and suggestions.
-By default this extension uses the official [golint](https://github.com/golang/lint) as a linter.
-
-You can change the default linter and use the more advanced [Go Meta Linter](https://github.com/alecthomas/gometalinter)
-by setting `go.lintTool` to "gometalinter" in your settings.
-
-Go meta linter uses a collection of various linters which will be installed for you by the extension.
-
-Some of the very useful linter tools:
-* [errcheck](https://github.com/kisielk/errcheck) checks for unchecked errors in your code.
-* [varcheck](https://github.com/opennota/check) finds unused global variables and constants.
-* [deadcode](https://github.com/tsenart/deadcode) finds unused code.
-
-If you want to run only specific linters (some linters are slow), you can modify your configuration to specify them:
-
-```javascript
- "go.lintFlags": ["--disable-all", "--enable=errcheck"],
-```
-
-Alternatively, you can use [megacheck](https://github.com/dominikh/go-tools/tree/master/cmd/megacheck) which
-may have significantly better performance than `gometalinter`, while only supporting a subset of the tools.
-
-To disable lint on save turn off `go.lintOnSave`
-
-## Format on save
-
-If you have Auto Save feature enabled, then you might want to disable the format on save feature so that the code doesnt keep changing under you. You can do this by adding the below in your settings:
-```
-"[go]": {
- "editor.formatOnSave": false
-}
-```
-
-By default, `goreturns` is the tool used for formatting. You can choose `goimports` or `gofmt` by changing the `go.formatTool` setting
-
-If you see your unused imports disappearing or unimported packages getting added automatically, thats the `goreturns` tool doing the magic behind the scenes.
-
diff --git a/docs/tasks.md b/docs/tasks.md
index 4aa9ea2..44c20b9 100644
--- a/docs/tasks.md
+++ b/docs/tasks.md
@@ -73,8 +73,3 @@
```
The above task would run all tests with `User` in their name.
-
-
-
-
-
diff --git a/docs/tools.md b/docs/tools.md
index 91e9acd..66428bd 100644
--- a/docs/tools.md
+++ b/docs/tools.md
@@ -1,6 +1,6 @@
# Tools
-This document describes the tools used to create the VS Code Go extension. Each feature is provided by a command-line tool written in Go, so if you experience an issue, it may be due to the underlying tool. Some tools are required for the functionality of the extension, while others are provide optional features.
+This document describes the tools that power the VS Code Go extension. Each feature is provided by a command-line tool written in Go, so if you experience an issue, it may be due to the underlying tool. Some tools are required for the functionality of the extension, while others are provide optional features.
Some of the features can be provided by multiple tools, and this can be configured through the extension's settings. For more details, see the [Documentation](#documentation), [Formatting](#formatting), and [Diagnostics](#diagnostics) sections below.
@@ -11,7 +11,7 @@
These tools will be installed by default when you install the extension. You can manually install or update all of these tools by running the `Go: Install/Update Tools` command. If any tools are missing, you will see an "Analysis Tools Missing" warning in the bottom-right corner of the editor, which will prompt you to install these tools.
-VS Code Go will install the tools to your `GOPATH` by default, but the tools will also be found if they are on your `PATH`. If you wish to use a separate `GOPATH` for tools only, you can configure this via the [`"go.toolsGopath"`](commands.md#toolsGopath) setting.
+VS Code Go will install the tools to your `GOPATH` by default, but the tools will also be found if they are on your `PATH`. If you wish to use a separate `GOPATH` for tools only, you can configure this via the [`"go.toolsGopath"`](settings.md#toolsGopath) setting.
## Table of Contents
@@ -88,7 +88,7 @@
This tool provides the [find references](features.md#find-references) and [find interface implementations](features.md#find-interface-implementations) features.
-It can also be used to provide the [go to definition](features.md#go-to-definition) via the [`"go.docsTool"`](commands.md#docsTool) setting (see [Customization](#Customization)).
+It can also be used to provide the [go to definition](features.md#go-to-definition) via the [`"go.docsTool"`](settings.md#docsTool) setting (see [Customization](#Customization)).
`guru` does not have support for Go modules, so we recommend using [`gopls`] for those features instead.
@@ -128,13 +128,13 @@
If `gogetdoc` does not work for you, a combination of the [`godef`] and [`godoc`] tools can be used. [`guru`](#guru) can also be used, but only for the [go to definition](features.md#go-to-definition) behavior.
-Configure this via the [`"go.docsTool"`](commands.md#docsTool) setting.
+Configure this via the [`"go.docsTool"`](settings.md#docsTool) setting.
### Formatting
Formatting tools are used by the [formatting and import organization](features.md#format-and-organize-imports) features.
-[`goreturns`] is used by default. It formats the file according to the industry standard [`gofmt`] style, organizes imports, and fills in default return values for functions. Other tools can be used for formatting instead; this can be configured with the [`"go.formatTool"`](commands.md#formatTool) setting.
+[`goreturns`] is used by default. It formats the file according to the industry standard [`gofmt`] style, organizes imports, and fills in default return values for functions. Other tools can be used for formatting instead; this can be configured with the [`"go.formatTool"`](settings.md#formatTool) setting.
**NOTE: [`goreturns`] does not have support for Go modules, so we recommend using [`goimports`] or [`gopls`] instead.**
@@ -152,7 +152,9 @@
**NOTE: [`gotype-live`] does not work with modules, so if you are using modules, we recommend using [`gopls`] instead.**
-Other lint tools can be used instead of [`golint`] by configuring the [`"go.lintTool"`](commands.md#lintTool) setting. Other options include:
+The command used to provide build errors on-save is `go build -i -o` or `go test -i -c -o` (for test files). The binary generated by the build is written to a temporary location.
+
+Other lint tools can be used instead of [`golint`] by configuring the [`"go.lintTool"`](settings.md#lintTool) setting. Other options include:
* [`staticcheck`]: This tool provides a great deal of useful checks that are not provided by `golint`. See the full list at [staticcheck.io/docs/checks](https://staticcheck.io/docs/checks). It is also officially supported by the [Go team at Google](https://staticcheck.io/sponsors).
* [`golangci-lint`]: This tool combines a number of existing lint tools, including [staticcheck](#staticcheck), into one interface.
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 2c1b77c..2b61c1f 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -1,3 +1,243 @@
# Troubleshooting
-[Troubleshooting Debugging](debugging.md#troubleshooting)
\ No newline at end of file
+Read this document when you encounter a problem with this extension. Still, remember that this extension has many different features and moving parts. This document can provide guidance, but many cases are not covered here.
+
+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).
+
+The guidance offered here is applicable in most situations, but **note that [debugging](debugging.md#troubleshooting) and [`gopls`](gopls.md) also have their own troubleshooting documentation.**
+
+## Overview
+
+* [Check Known Issues](#check-known-issues)
+* [Check your set up](#check-your-set-up)
+ * [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)
+
+### Check [Known Issues](#known-issues)
+
+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.
+
+### 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.
+
+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).
+
+### Check your set-up
+
+First, make sure you understand the difference between [`GOPATH`](gopath.md) and [module](modules.md) modes and know which mode you are using. You can run `go version` and `go env` in the [integrated terminal] is configured as you expect.
+
+<!--TODO(rstambler): Locate Configured Go Tools should also print `go env` I think.-->
+
+This extension supports a few meta-commands that can be used for investigation. Try running `Go: Locate Configured Go Tools`. The output should look like:
+
+```bash
+Checking configured tools....
+GOBIN: undefined
+toolsGopath:
+gopath: /path/to/gopath
+GOROOT: /path/to/go
+PATH: /path/to/:/another/path:/some/path
+
+ 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
+```
+
+If your `GOPATH` or `GOROOT` is undefined, that may indicate a problem. Read more about [setting up your `GOPATH`](gopath.md). A missing `GOROOT` means that you haven't installed Go correctly. This topic is covered in the [Getting Started guide](../README.md#install-go).
+
+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` command.
+
+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.
+
+Common culprits include:
+
+* [`go.inferGopath`](settings.md#inferGopath)
+* [`go.toolsGopath`](settings.md#inferGopath)
+* [`go.alternateTools`](settings.md#inferGopath)
+* [`go.useLanguageServer`](settings.md#useLanguageServer)
+
+Read up on those settings, as well as all of the other [available settings](settings.md). Make sure that you have configured the right settings.
+
+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#toolsEnvVars). Other settings are available to override specific variables, like your `GOPATH`, which can be set through the [`go.gopath`](settings.md#gopath) setting as well.
+
+### Update tools
+
+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` command.
+
+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. If not, you can follow these suggestions.
+
+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#toolsGopath), you should look in that directory.
+
+If that doesn't work, something may have gone wrong in the repository that contains the tool. Check if there are any issues filed in that 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#troubleshooting), 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 the [VS Code Go 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).
+
+First, make sure you have already followed the [investigation steps](#investigate) above. 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` or by running `go install` on the command-line. If you have enabled [`go.buildOnSave`](settings.md#buildOnSave) or [`go.gocodeAutobuild`](settings.md#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.
+
+```json5
+"[go]": {
+ "editor.tabSize": 8
+}
+```
+
+### Diagnostics
+
+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.
+
+#### Build errors
+
+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 it does, try copying the exact command used by VS Code Go uses. 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 the [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
diff --git a/smoke-test.md b/smoke-test.md
new file mode 100644
index 0000000..53ed227
--- /dev/null
+++ b/smoke-test.md
@@ -0,0 +1,82 @@
+# Smoke Test
+
+Before releasing a new version of the extension, please run the following smoke test to make sure that all features are working.
+
+## Set up
+
+First, clone the [golang.org/x/example](https://github.com/golang/example). At the time of writing (June 2020), this repository has not changed since 2017. If it has changed since, these steps may not be exactly reproducible and should be adjusted.
+
+<!--TODO(rstambler): Maintain our own smoke tests, or add a go.mod file to this repository.-->
+For now, we smoke test the extension only in `GOPATH` mode.
+
+If it does not already exist:
+
+```bash
+mkdir $GOPATH/src/github.com/golang
+```
+
+Then,
+
+```bash
+cd $GOPATH/src/github.com/golang
+git clone https://github.com/golang/example
+cd example
+```
+
+Next, [build and sideload the modified Go extension](contributing.md#sideload) and open the `example/hello` directory. Open `hello.go`.
+
+## Test code navigation
+
+1. Go to definition on `fmt.Println`.
+2. Go to definition on `stringutil.Reverse`.
+3. Find all references of `fmt.Println`.
+4. Find all references of `stringutil.Reverse`.
+5. Hover over `fmt.Println`.
+6. Hover over `stringutil.Reverse`.
+
+## Test autocompletion
+
+<!--TODO(rstambler): We should require the user install another package in their GOPATH and expect unimported completions from that package.-->
+
+1. Trigger autocompletion (Ctrl+Space) after `fmt.`.
+2. Trigger autocompletion (Ctrl+Space) after `stringutil.`.
+3. Enter a newline in the `main` function and type `fmt.`.
+4. Enter a newline in the `main` function and type `parser.`. Expect suggestions from the unimported standard library `go/parser` package.
+5. Enter a newline in the `main` function and type `fmt.`. Select the `fmt.Println` completion and observe the outcome. Toggle the `go.useCodeSnippetsOnFunctionSuggest` setting to ensure that placeholders are provided.
+6. Test signature help by manually triggering it (Ctrl+Shift+Space) while completing `fmt.Println`.
+7. Test signature help by manually triggering it (Ctrl+Shift+Space) while completing `stringutil.Reverse`.
+
+## Test diagnostics
+
+Enable `go.buildOnSave`, `go.vetOnSave`, and `go.lintOnSave`.
+
+1. Add `var x int` to the `main` function and expect a build diagnostic.
+2. Add `fmt.Printf("hi", 1)` and expect a vet diagnostic.
+3. Add the following function to the bottom of the file and expect a lint diagnostic.
+
+ ```go
+ // Hello is hi.
+ func Hi() {}
+ ```
+
+You can also try toggling the `"package"` and `"workspace"` configurations for these settings.
+
+## Test formatting and import organization
+
+1. Hit enter 3 times in the `main` function and save. Expect formatting to remove all but one line.
+2. Remove the `"fmt"` import. Save and expect it to return.
+3. Remove the `"github.com/golang/example/stringutil"` import. Save and expect it to return.
+4. Confirm that the `Go: Add Import` command works (add `"archive/tar"`).
+
+## Test renaming
+
+1. Add the following to the `main` function, then rename `x` to `y`.
+
+ ```go
+ var x int
+ fmt.Println(x)
+ ```
+
+2. Rename `stringutil.Reverse`. `reverse.go` and `reverse_test.go` should be dirtied.
+
+<!--TODO(rstambler): Other features should also be tested. Not sure if this whole smoke test process is worth it or will ever be followed.-->
\ No newline at end of file
diff --git a/src/debugAdapter/README.md b/src/debugAdapter/README.md
index 583dd6d..c24d4f8 100644
--- a/src/debugAdapter/README.md
+++ b/src/debugAdapter/README.md
@@ -1,62 +1,3 @@
-# Go Debug Adapter
+# Debug Adapter
-The Debug Adapter code runs in a separate Nodejs process spawned by Visual Studio Code when you debug Go code.
-
-Please see [The Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) to understand how the Debug Adapter acts as an intermediary between VS Code and the debugger which in case of Go is [delve](https://github.com/go-delve/delve). We are currently working on utilizing `delve`'s [native DAP implementation](https://github.com/go-delve/delve/tree/master/service/dap).
-
-## Set up local dev environment
-
-Clone this [repo](https://go.googlesource.com/vscode-go) and then run `npm install`
-
-```shell
-git clone https://go.googlesource.com/vscode-go
-cd vscode-go
-npm install
-```
-
-#### Debug Adapter compilation:
-You might want to compile the debug adapter to verify your changes. Additionally, debug symbols must be updated whenever you want to set breakpoints accurately. For the vscode-go project, there is a build task available which will start the Typescript compiler in watch mode, detecting errors on code changes and updating debug symbols automatically.
-
-The project on the debugAdapter folder level doesn´t have this task included, but the `tsc` compiler can be started manually via the following steps:
-
-1. Install `tsc`, if you haven't done so yet:
-```shell
-npm install -g typescript
-```
-2. In the debugAdapter directory, start `tsc` in watch mode, using this extension's Typescript configuration rules:
-```shell
-tsc -w -p ../../
-```
-
-## Debugging the Go Debug Adapter
-
-This is the option you would take if you want to understand or change the way the Go debug adapter interacts with delve.
-
-This lets you debug the code in the `goDebug.ts` file which powers the debug adapter which runs in a different Nodejs process than the rest of the extension.
-Therefore, you won't be able to debug the code powering the rest of the extension.
-
-1. Open the `vscode-go` folder in VS Code. Choose the `Launch as server` debug configuraion from the drop down in the debug viewlet. Add a breakpoint in the desired localtion in the `vscode-go/src/debugAdapter/goDebug.ts` file
-2. Open the Go application that you want to debug in another instance of VS Code. Create a debug configuration if it doesnt exist. In this configuration add `"debugServer": 4711` in the root of the configuration. Start debugging your Go application and the breakpoint in the `goDebug.ts` file in the other VS Code instance will be hit.
-
-## Debugging the Go Debug Adapter as well as the rest of the extension
-
-This is the option you would take if you have changes both in the `goDebug.ts` file (which powers the debug adapter) as well any of the other files in this project.
-This setup involves three instances of Visual Studio Code:
-
-1. Open the `vscode-go` folder in one instance. Choose the `Launch Extension` debug target and hit F5. This will launch a second instance of Visual Studio Code.
-2. In the second instance, open the Go application you'd like to debug. Here, create a new Go debug configuration pointing at the program you want to debug. Add `"debugServer": 4711` in the root of the configuration.
-3. Open another instance of Code on the `vscode-go/src/debugAdapter` folder. In this instance hit F5 to launch the debug adapter in server mode under the debugger.
-4. Go back to the second instance and hit F5 to debug your Go code. Debuggers from the other two Code windows are attached to the Go debug adapter and the Go language integration respectively, so you can set breakpoints, step through code and inspect state as needed.
-
-## Debugging the Debug Adapter as well as Visual Studio Code
-
-In some edge cases (like veryfing workbench behavior and state before executing debug adapter apicalls) debugging VS Code itself can be helpful. Once you ensure that you can [build and run Visual Studio Code](https://github.com/Microsoft/vscode/wiki/How-to-Contribute#build-and-run) from source successfully, follow the below steps:
-
-1. Follow the [preliminary steps to build vscode-go](#set-up-local-dev-environment)
-2. Sideload the your local vscode-go extension to the locally run Visual Studio Code. This is done by copying the contents of the vscode-go folder into `$HOME/.vscode-oss-dev/extensions/ms-vscode.go` (the location may vary by OS)
-3. Open the `vscode` folder in Visual Studio Code. Launch the VS Code debug instance (OSS - Code) by choosing the `Launch VS Code` debug configuraion from the drop down in the debug viewlet. Add a breakpoint in the desired localtion.
-4. In another instance of Visual Studio Code, open the `vscode-go` folder. Choose the `Launch as server` debug configuration from the drop down in the debug viewlet. Add a breakpoint in the desired localtion in the `vscode-go/src/debugAdapter/goDebug.ts` file
-5. Open the Go application that you want to debug in the OSS Code instance initiated in step 3. Create a debug configuration if it doesnt exist. In this configuration add `"debugServer": 4711` in the root of the configuration. Start debugging your Go application and the breakpoint in the `goDebug.ts` file in the other VS Code instance will be hit, along with the breakpoints set up in the vscode files
-
-
-
+See the [contribution documentation](../../docs/contributing.md) to learn how to develop the debug adapter.
