[release] 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 <[email protected]>
(cherry picked from commit cf9d16b)
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/236959

Author: stamblerre

.vscode/launch.json

@@ -88,7 +88,7 @@
 				"${workspaceFolder}/out/test/unit"
 			],
 			"internalConsoleOptions": "openOnSessionStart"
-		}
+		},
 	],
 	"compounds": [
 		{

README.md

@@ -13,18 +13,17 @@ Take a look at the [Changelog](CHANGELOG.md) to learn about new features.
 ## 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 @@ Here are some additional resources for learning about how to set up your Go proj
 
 **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 @@ To activate the extension, open any directory or workspace containing Go code.
 
 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 @@ To opt-in to the language server, set [`"go.useLanguageServer"`](docs/commands.m
 
 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 @@ We welcome your contributions and thank you for working to improve the Go develo
 
 This project follows the [Go Community Code of Conduct](https://golang.org/conduct). If you encounter an issue, please mail [email protected].
 
-## License
+## [License](LICENSE)
 
 [MIT](LICENSE)
 

docs/contributing.md

@@ -6,11 +6,13 @@ This guide will explain the process of setting up your development environment t
 
 * [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 @@ If you wish to work on an existing issue, please add a comment saying so, as som
 
 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 @@ The VS Code Go maintainers are reachable via the issue tracker and the [#vscode-
     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 @@ You can also set breakpoints, which will work as you run the extension.
 
 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`).

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.