[release] docs: rewrite debugging.md, testing.md, smoke-test.md, etc.
Rewrote a number of documents. Notable changes:
- Cleaned up and updated the debugging documentation. Some more work
still needs to be done, but I think it's in pretty good shape.
- Move build/README.md to docs/testing.md. I think it fits better with
the other docs, and I expect most of the build directory will be going
away soon? Hana, let me know what you think because I can also move it
back.
- Separated settings.md from commands.md. Ran out of steam when trying
to finish commands.md, but I'll try to work on it more next. Haven't
updated all of the incorrect references to commands.md yet, but
that's for the next CL.
- Updated and cleaned up the smoke test. Not sure if we'll ever use it,
but it's not a bad thing to have, and I caught a gopls bug with it.
Change-Id: Ie9ed8187a0597d36f5960d77fd999d14366bbe74
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/236379
Reviewed-by: Hyang-Ah Hana Kim <hyangah@gmail.com>
(cherry picked from commit 4a34f9b98d30ccacfc69ab55357d35a72ec9494f)
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/236958
diff --git a/build/Dockerfile b/build/Dockerfile
index 97fd3c0..99e79f1 100644
--- a/build/Dockerfile
+++ b/build/Dockerfile
@@ -1,3 +1,5 @@
+# This Docker container is used for testing on GCB.
+
FROM golang:1.14 AS gobuilder
ENV GO111MODULE on
diff --git a/build/README.md b/build/README.md
new file mode 100644
index 0000000..d7c4e17
--- /dev/null
+++ b/build/README.md
@@ -0,0 +1 @@
+# See the [testing documentation](../docs/testing.md)
diff --git a/docs/Smoke-Test.md b/docs/Smoke-Test.md
index 2a5aba9..53ed227 100644
--- a/docs/Smoke-Test.md
+++ b/docs/Smoke-Test.md
@@ -1,38 +1,82 @@
-**Pre-requisites for testing Go extension if you don't already have Go installed and the extension set up**
+# Smoke Test
-1. Install [Go](https://golang.org/doc/install#install)
-2. Run `go get github.com/golang/example/hello`
-3. Sideload the Go extension and open the folder $HOME/go/src/gitHub.com/golang/example in VS Code
-4. Open any Go file. You will see "Analysis Tools Missing" in the status bar. Click on it to install the Go tools that the extension needs.
+Before releasing a new version of the extension, please run the following smoke test to make sure that all features are working.
-**Features to Smoke Test:**
+## Set up
-Try the below features for functions, structs and interfaces from current/std/third party packages
-- Goto and Peek Definition
-- Find References
-- Hover Info
+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.
-Try the below for functions in built-in (fmt, strings, math etc) and custom packages (stringutil in the hello project)
-- Auto complete
-- Auto complete for unimported packages
-- Set `go.useCodeSnippetsOnFunctionSuggest` to true and check if code snippets show up for functions
-- Signature Help
+<!--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.
-Enable build, vet, lint and format On Save features, make a change in a go file and save. Try both values "package" and "workspace" for the settings.
-- The output channel for Go should show build, vet and linting results
-- If there were errors, red squiggle lines should show up in the editor
-- Remove comments on an exported member (anything whose name starts with a capital letter), and make sure linter asks you to add the comment
-- Add tabs and extra lines, remove an import: formatting should fix all of these
+If it does not already exist:
-Rename
-- Rename a local variable, rename should work, file should go to a dirty state
-- Rename an exported function (eg: Reverse in the hello project), rename should work across files, all affected files should open and be in dirty state
+```bash
+mkdir $GOPATH/src/github.com/golang
+```
-Add imports
-- The command "Go: Add import" should give a list of packages that can be imported.
-- Selecting one of these should add an import to the current go file
-- Already imported packages in the current file should not show up in the list
+Then,
-Other features:
-- File outline
-- Debugging
\ No newline at end of file
+```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/docs/commands.md b/docs/commands.md
index 6ee2511..73f9a5b 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -1,88 +1,149 @@
-# Settings and Commands
+# Commands
-To view a complete list of the commands and settings for this extension:
+In addition to the integrated editing features, this extension offers a number of commands, which can be executed manually through the [Command Palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) (Ctrl+Shift+P).
+
+Some of these commands are also available in the VS Code context menu (right click). To control which of these commands show up in the editor context menu, update the [`"go.editorContextMenuCommands"`](settings.md#editorContextMenuCommands) setting.
+
+All commands provided by this extension have the prefix "`Go:` ".
+
+## Latest changes
+
+The commands described below are up-to-date as of June 2020. We do our best to keep documentation current, but if a command is missing, you can always consult the full list in the Extensions view.
+
+To view this list:
1. Navigate to the Extensions view (Ctrl+Shift+X).
-2. Find the Go extension, click on it to open the Extension Editor.
+2. Find the Go extension and click on it to open the Extension Editor.
3. Click on the `Feature Contributions` tab.
-4. Scroll away.
+4. Scroll through the list under `Commands`.
-<!--TODO(rstambler): This image needs to be updated.-->
-
+Finally, you can also see a full list by using a meta command: `Go: Show All Commands...`.
-## Settings
+## Detailed list
-You can configure your settings by modifying your [User or Workspace Settings](https://code.visualstudio.com/docs/getstarted/settings). To navigate to your settings, open the Command Palette (Ctrl+Shift+P) and search for "settings". The simplest way to modify your settings is through "Preferences: Open Settings (UI)".
+Below is a detailed list of commands. They are categorized into [code editing and generation](#code-editing-and-generation), [testing and benchmarking](#testing-and-benchmarking), [build, lint, and vet](#build-lint-and-vet), [miscellaneous](#miscellaneous), and [troubleshooting](#troubleshooting). You will find the [troubleshooting](#troubleshooting) commands helpful when diagnosing an issue with the extension (learn more in the [Troubleshooting documentation](troubleshooting.md)).
-**NOTE: Most of these settings don't apply if you are using [`gopls`](gopls.md). Learn more about `gopls`-specific settings in this [documentation](https://github.com/golang/tools/blob/master/gopls/doc/settings.md).**
+### Code editing and generation
-A list of popular and notable settings can be found below.
+<!--Note: Try to keep this list in roughly alphabetical/logical order.-->
-### docsTool
+#### [`Go: Add Import`](features.md#add-import)
-One of `"godoc"`, `"gogetdoc"`, or `"guru"` (`gogetdoc` is the default). This is the tool used by the [go to definition](features.md#go-to-definition), [signature help](features.md#signature-help), and [quick info on hover](features.md#quick-info-on-hover) features. See more information about each of these tools in the [Documentation](tools.md#Documentation) section.
+<!--TODO(rstambler): Confirm exactly how this works.-->
+Manually add an import to your file. See [Add import](features.md#add-import).
-### formatTool
+#### [`Go: Add Package to Workspace`]()
-One of `"gofmt"`, `"goimports"`, `"goreturns"`, and `"goformat"` (`goreturns` is the default). This is the tool used by the [formatting and import organization](features.md#formatting-and-import-organization) features. See more information about each of these tools in the [Formatting](tools.md#Formatting) section.
+#### [`Go: Add Tags to Struct Fields`](features.md#add-struct-tags)
-### lintTool
+Automatically generate [tags](https://pkg.go.dev/reflect?tab=doc#StructTag) for your struct. See [Add or remove struct tags](features.md#add-or-remove-struct-tags).
-One of `"golint"`, `"staticcheck"`, `"golangci-lint"`, and `"revive"` (`golint` is the default). This is the tool used by the [lint-on-save](features.md#lint-on-save) feature. See more information about each of these tools in the [Diagnostics](tools.md#Diagnostics) section.
+#### [`Go: Remove Tags From Struct Fields`](features.md#add-struct-tags)
-### lintFlags
+Removes [tags](https://pkg.go.dev/reflect?tab=doc#StructTag) from the selected struct fields. See [Add or remove struct tags](features.md#add-or-remove-struct-tags).
-This setting can be used to pass additional flags to your lint tool of choice.
+#### [`Go: Fill struct`](features.md#fill-struct-literals)
-Most linters can be configured via special configuration files, but you may still need to pass command-line flags. The configuration documentation for each supported linter is listed here:
+Fill a struct literal with default values. See [Fill struct](features.md#fill-struct-literals).
-* [`staticcheck`](https://staticcheck.io/docs/#configuration)
-* [`golangci-lint`](https://golangci-lint.run/usage/configuration/)
-* [`revive`](https://github.com/mgechev/revive#command-line-flags)
+#### [`Go: Generate Interface Stubs`](features.md#generate-interface-implementation)
-#### Examples
+Generate method stubs for given interface. See [Generate interface implementation](features.md#generate-interface-implementation).
-Enable all [`golangci-lint`] linters and only show errors in new code:
+#### [`Go: Generate Unit Tests For Function`](features.md#generate-unit-tests)
-```json5
-"go.lintFlags": ["--enable-all", "--new"]
-```
+Generate unit tests for the selected function in the current file. See [Generate unit tests](features.md#generate-unit-tests).
-Configure `revive` to exclude `vendor` directories and apply extra configuration with a `config.toml` file:
+#### [`Go: Generate Unit Tests For File`](features.md#generate-unit-tests)
-```json5
-"go.lintFlags": [
- "-exclude=vendor/...",
- "-config=${workspaceFolder}/config.toml"
-]
-```
+Generate unit tests for the current file. See [Generate unit tests](features.md#generate-unit-tests).
-### Commands
+#### [`Go: Generate Unit Tests For Package`](features.md#generate-unit-tests)
-In addition to integrated editing features, the extension also provides several commands in the Command Palette for working with Go files:
+Generate unit tests for the current package. See [Generate unit tests](features.md#generate-unit-tests).
-* `Go: Add Import` to add an import from the list of packages in your Go context
-* `Go: Current GOPATH` to see your currently configured GOPATH
-* `Go: Test at cursor` to run a test at the current cursor position in the active document
-* `Go: Test Package` to run all tests in the package containing the active document
-* `Go: Test File` to run all tests in the current active document
-* `Go: Test Previous` to run the previously run test command
-* `Go: Test All Packages in Workspace` to run all tests in the current workspace
-* `Go: Generate Unit Tests For Package` Generates unit tests for the current package
-* `Go: Generate Unit Tests For File` Generates unit tests for the current file
-* `Go: Generate Unit Tests For Function` Generates unit tests for the selected function in the current file
-* `Go: Install Tools` Installs/updates all the Go tools that the extension depends on
-* `Go: Add Tags` Adds configured tags to selected struct fields.
-* `Go: Remove Tags` Removes configured tags from selected struct fields.
-* `Go: Generate Interface Stubs` Generates method stubs for given interface
-* `Go: Fill Struct` Fills struct literal with default values
-* `Go: Run on Go Playground` Upload the current selection or file to the Go Playground
+#### [`Go: Extract to function`]()
-You can access all of the above commands from the command palette (`Cmd+Shift+P` or `Ctrl+Shift+P`).
+#### [`Go: Extract to variable`]()
-A few of these are available in the editor context menu as an experimental feature as well. To control which of these commands show up in the editor context menu, update the setting `go.editorContextMenuCommands`.
+### Testing and benchmarking
+
+#### [`Go: Test Function at Cursor`](features.md#test-and-benchmark-in-the-editor)
+
+Run the test function at the current cursor position in the file.
+
+#### [`Go: Subtest at Cursor`]()
+
+#### [`Go: Benchmark Function At Cursor`]()
+
+#### [`Go: Debug Test At Cursor`]()
+
+#### [`Go: Test File`](features.md#test-and-benchmark-in-the-editor)
+
+Run all of the tests in the current file.
+
+#### [`Go: Benchmark File`]()
+
+#### [`Go: Test Package`](features.md#test-and-benchmark-in-the-editor)
+
+Run all of tests in the current package.
+
+#### [`Go: Benchmark Package`]()
+
+#### [`Go: Test Previous`](features.md#test-and-benchmark-in-the-editor)
+
+Re-run the most recently executed test command.
+
+#### [`Go: Test All Packages In Workspace`](features.md#test-and-benchmark-in-the-editor)
+
+Run all of the tests in the current workspace.
+
+#### [`Go: Cancel Running Tests]()
+
+#### [`Go: Toggle Test File`]()
+
+#### [`Go: Apply Cover Profile]()
+
+#### [`Go: Toggle Test Coverage In Current Package`]()
+
+### Build, lint, and vet
+
+#### [`Go: Build Current Package`]()
+
+#### [`Go: Lint Current Package`]()
+
+#### [`Go: Vet Current Package`]()
+
+#### [`Go: Build Workspace`]()
+
+#### [`Go: Lint Workspace`]()
+
+#### [`Go: Vet Workspace`]()
+
+#### [`Go: Install Current Package`]()
+
+### Miscellaneous
+
+#### [`Go: Restart Language Server`]()
+
+#### [`Go: Run on Go Playground`](features.md#go-playground)
+
+Upload the current selection or file to the Go Playground ([play.golang.org](https://play.golang.org)). See [Go Playground](features.md#go-playground).
+
+### Troubleshooting
+
+#### `Go: Current GOPATH`
+
+See the current value of GOPATH. This is not equivalent to `go env GOPATH`, as your VS Code settings may have altered the value of `GOPATH` used by the extension.
+
+#### [`Go: Install/Update Tools`](tools.md)
+
+Install or update the Go tools on which the extension depends. Tools can be installed or updated all at once, or individual tools can be selected.
+
+#### [`Go: Locate Configured Go Tools`]()
[`golint`]: https://pkg.go.dev/golang.org/x/lint/golint?tab=overview
[`staticcheck`]: https://pkg.go.dev/honnef.co/go/tools/staticcheck?tab=overview
[`golangci-lint`]: https://golangci-lint.run/
-[`revive`]: https://pkg.go.dev/github.com/mgechev/revive?tab=overview
\ No newline at end of file
+[`revive`]: https://pkg.go.dev/github.com/mgechev/revive?tab=overview
+[`gomodifytags`]: tools.md#gomodifytags
diff --git a/docs/contributing.md b/docs/contributing.md
index 115f4a2..4008f94 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -92,5 +92,9 @@
Once you've sent out your change, a maintainer will take a look at your contribution within a few weeks. If you don't hear back in that time, feel free to ping the issue or send a message to the [#vscode-dev] channel of the [Gophers Slack].
+## [Continuous Integration](testing.md)
+
+The extension's test suite will run on your change once it has been mailed. If you have contributed via a GitHub pull request (PR), the test results will be provided via a [GitHub Action](testing.md#testing-via-github-actions) result on the PR. If you have mailed a Gerrit changelist (CL) directly, tests will run in [Google Cloud Build](testing.md#testing-via-gcb), and the results will be posted back on the CL. As of June 2020, the GCB and Gerrit integration is not yet ready, so the results of the CI run **will not** appear on the Gerrit changelist. Instead, if your change fails on GCB, your reviewer will notify you and provide you with the relevant logs.
+
[#vscode-dev]: https://gophers.slack.com/archives/CUWGEKH5Z
[Gophers Slack]: https://invite.slack.golangbridge.org/
diff --git a/docs/debugging.md b/docs/debugging.md
index a99a2b1..c9723ff 100644
--- a/docs/debugging.md
+++ b/docs/debugging.md
@@ -2,16 +2,20 @@
The Go debugger is [Delve]. The [Delve] repository has detailed instructions, so we recommend taking a look at the [Delve documentation](https://github.com/go-delve/delve/tree/master/Documentation).
-## Table of Contents
+## Overview
* [Features](#features)
* [Set up](#set-up)
* [Installation](#installation)
* [Configuration](#configuration)
-* [Launch Configuration](#launch-configuration)
-* [Debugging in WSL](#debugging-in-wsl)
+* [Launch Configurations](#launch-configurations)
+ * [Specifying build tags](#specifying-build-tags)
+ * [Using VS Code Variables](#using-vs-code-variables)
+ * [Snippets](#snippets)
+* [Debugging on Windows Subsystem for Linux (WSL)](#debugging-on-windows-subsystem-for-linux-wsl)
* [Remote Debugging](#remote-debugging)
-* [Common Issues](#common-issues)
+* [Troubleshooting](#troubleshooting)
+ * [Common issues](#common-issues)
## Set up
@@ -26,267 +30,330 @@
### Configuration
-The below settings are used by the debugger. You may not need to add/change any of them to have debugging working in simple cases, but do give them a read sometime
-- `go.gopath`. See [GOPATH in VS Code](gopath.md)
-- `go.inferGopath`. See [GOPATH in VS Code](gopath.md)
-- `go.delveConfig`
- - `apiVersion`: Controls the version of delve apis to be used when launching the delve headless server. Default is 2.
- - `dlvLoadConfig`: Not applicable when `apiVersion` is 1. The configuration passed to delve. Controls [various features of delve](https://github.com/Microsoft/vscode-go/blob/0.6.85/package.json#L431-L468) that affects the variables shown in the debug pane.
- - `maxStringLen`: maximum number of bytes read from a string
- - `maxArrayValues`: maximum number of elements read from an array, a slice or a map
- - `maxStructFields`: maximum number of fields read from a struct, -1 will read all fields
- - `maxVariableRecurse`: how far to recurse when evaluating nested types
- - `followPointers`: requests pointers to be automatically dereferenced
-
+You may not need to configure any settings to start debugging your programs, but you should be aware that the debugger looks at the following settings.
-Some common cases where you might want to tweak the configurations passed to delve
-- Change the default cap of 64 on string and array length when inspecting variables in the debug viewlet.
-- Evaluate variables that are nested when inspecting them in the debug viewlet.
+* Related to [`GOPATH`](gopath.md):
+ * [`go.gopath`](settings.md#gopath)
+ * [`go.inferGopath`](settings.md#inferGopath)
+* `go.delveConfig`
+ * `apiVersion`: Controls the version of the Delve API used when launching the Delve headless server (default: `2`).
+ * `dlvLoadConfig`: The configuration passed to Delve, which controls how variables are shown in the Debug pane. Not applicable when `apiVersion` is 1.
+ * `maxStringLen`: Maximum number of bytes read from a string (default: `64`).
+ * `maxArrayValues`: Maximum number of elements read from an array, slice, or map (default: `64`).
+ * `maxStructFields`: Maximum number of fields read from a struct. A setting of `-1` indicates that all fields should be read (default: `-1`).
+ * `maxVariableRecurse`: How far to recurse when evaluating nested types (default: `1`).
+ * `followPointers`: Automatically dereference pointers (default: `true`).
+ * `showGlobalVariables`: Show global variables in the Debug view (default: `true`).
-## Set up configurations in launch.json
+There are some common cases when you might want to tweak the Delve configurations.
-Once delve is installed, run the command `Debug: Open launch.json`. If you didnt already have a launch.json file, this will create one with the below default configuration which can be used to debug the current package.
+* To change the default cap of 64 on string and array length when inspecting variables in the Debug view, set `maxStringLen`. (See a related known issue: [golang/vscode-go#126](https://github.com/golang/vscode-go/issues/126)).
+* To evaluate nested variables in the Debug viewlet, set `maxVariableRecurse`.
-```json
+## Launch Configurations
+
+To get started debugging, run the command `Debug: Open launch.json`. If you did not already have a `launch.json` file for your project, this will create one for you. It will contain this default configuration, which can be used to debug the current package.
+
+```json5
{
- "version": "0.2.0",
- "configurations": [
- {
- "name": "Launch",
- "type": "go",
- "request": "launch",
- "mode": "auto",
- "program": "${fileDirname}",
- "env": {},
- "args": []
- }
- ]
+ "version": "0.2.0",
+ "configurations": [
+ {
+ "name": "Launch",
+ "type": "go",
+ "request": "launch",
+ "mode": "auto",
+ "program": "${fileDirname}",
+ "env": {},
+ "args": []
+ }
+ ]
}
```
+There are some more properties that you can adjust in the debug configuration. See the table below:
-Below is some more information on some common properties you can tweak in the debug configuration:
+Property | Description
+-------- | -----------
+name | The name for your configuration as it appears in the drop-down in the Debug view.
+type | Always leave this set to `"go"`. VS Code uses this setting to determine which extension should be used for debugging your code.
+request | One of `launch` or `attach`. Use `attach` when you want to attach to an already running process.
+mode | For `launch` requests, one of `auto`, `debug`, `remote`, `test`, or `exec`. For `attach` requests, use `local` or `remote`.
+program | In `test` or `debug` mode, this refers to the absolute path to the package or file to debug. In `exec` mode, this is the already built binary file to debug. Not applicable to `attach` requests.
+env | Environment variables to use when debugging. Use the format: `{ "ENVNAME": "ENVVALUE" }`.
+envFile | Absolute path to a file containing environment variable definitions. The environment variables passed in via the `env` property override the ones in this file.
+args | Array of command-line arguments that will be passed in to the program being debugged.
+showLog | If `true`, Delve logs will be printed in the Debug Console panel.
+logOutput | Comma-separated list of Delve components (`debugger`, `gdbwire`, `lldbout`, `debuglineerr`, `rpc`) that should produce debug output when `showLog` is `true`.
+buildFlags | Build flags to be passed to the Go compiler.
+remotePath | If remote debugging (`mode`: `remote`), this should be the absolute path to the file being debugged on the remote machine. See the section on [Remote Debugging](#remote-debugging) for further details. [golang/vscode-go#45](https://github.com/golang/vscode-go/issues/45) is also relevant.
+processId | This is the process ID of the executable you want to debug.Applicable only when using the `attach` request in `local` mode.
-Property | Description
-------- | ------
-name | Name for your configuration that appears in the drop down in the Debug viewlet
-type | Always set to "go". This is used by VS Code to figure out which extension should be used for debugging your code
-request | Either of `launch` or `attach`. Use `attach` when you want to attach to an already running process.
-mode | For launch requests, either of `auto`, `debug`, `remote`, `test`, `exec`. For attach requests, use either `local` or `remote`
-program | Absolute path to the package or file to debug when in `debug` & `test` mode, or to the pre-built binary file to debug in `exec` mode. Not applicable to attach requests.
-env | Environment variables to use when debugging. Example: `{ "ENVNAME": "ENVVALUE" }`
-envFile | Absolute path to a file containing environment variable definitions. The environment variables passed in the `env` property overrides the ones in this file.
-args | Array of command line arguments that will be passed to the program being debugged.
-showLog | Boolean indicating if logs from delve should be printed in the debug console
-logOutput | Comma separated list of delve components (`debugger`, `gdbwire`, `lldbout`, `debuglineerr`, `rpc`) that should produce debug output when `showLog` is set to `true`.
-buildFlags | Build flags to be passed to the Go compiler
-remotePath | Absolute path to the file being debugged on the remote machine in case of remote debugging i.e when `mode` is set to `remote`. See the section on [Remote Debugging](#remote-debugging) for details
-processId | Applicable only when using the `attach` request with `local` mode. This is the id of the process that is running your executable which needs debugging.
+### Specifying [build tags](https://golang.org/pkg/go/build/#hdr-Build_Constraints)
+If your program contains [build tags](https://golang.org/pkg/go/build/#hdr-Build_Constraints), you can use the `buildFlags` property. For example, if you build your code with:
-### Using VS Code variables in debug configuration
+```bash
+go build -tags=whatever
+```
-Any property in the debug configuration that takes a folder/file path can use the below VS Code variables
+Then, set:
-* `${workspaceFolder}` to debug package at the root of the workspace that is opened in VS Code
-* `${file}` to debug the current file.
-* `${fileDirname}` to debug the package to which the current file belongs to.
+```json5
+"buildFlags": "-tags=whatever"
+```
-### Using build tags
+in your launch configuration. This property supports multiple tags, which you can set by using single quotes. For example:
-If your build needs build tags (e.g. `go build -tags=whatever_tag`), then add the parameter `buildFlags` with the content `"-tags=whatever_tag"`. Multiple tags are supported, by *enclosing them in single quotes within the double quotes* like so: `"-tags='first_tag second_tag third_tag'"`.
+```json5
+"buildFlags": "-tags='first,second,third'"
+```
+<!--TODO(rstambler): Confirm that the extension works with a comma (not space) separated list.-->
+### Using [VS Code variables]
+Any property in the launch configuration that requires a file path can be specified in terms of [VS Code variables]. Here are some useful ones to know:
-## Snippets for Debug Configurations
+* `${workspaceFolder}` refers to the root of the workspace opened in VS Code.
+* `${file}` refers to the currently opened file.
+* `${fileDirname}` refers to the directory containing the currently opened file. This is typically also the name of the Go package containing this file, and as such, can be used to debug the currently opened package.
-You can make use of snippets for the debug configuration while editing the launch.json file.
-Type "Go" and you will get snippets for debugging current file/package, a test function etc.
+### Snippets
-### Sample configuration to debug the current file
+In addition to [VS Code variables], you can make use of [snippets] when editing the launch configuration in `launch.json`.
-```json
+When you type `go` in the `launch.json` file, you will see snippet suggestions for debugging a given test function or the current file or package.
+
+Below are the available sample configurations:
+
+#### Debug the current file (`Go: Launch file`)
+
+Recall that `${file}` refers to the currently opened file (see [Using VS Code Variables](#using-vs-code-variables)).
+
+```json5
{
- "name": "Launch file",
- "type": "go",
- "request": "launch",
- "mode": "auto",
- "program": "${file}"
+ "name": "Launch file",
+ "type": "go",
+ "request": "launch",
+ "mode": "auto",
+ "program": "${file}"
}
```
-### Sample configuration to debug a single test
+#### Debug a single test function (`Go: Launch test function`)
-```json
+Recall that `${workspaceFolder}` refers to the current workspace (see [Using VS Code Variables](#using-vs-code-variables)). You will need to manually specify the function name instead of `"MyTestFunction"`.
+
+```json5
{
- "name": "Launch test function",
- "type": "go",
- "request": "launch",
- "mode": "test",
- "program": "${workspaceFolder}",
- "args": [
- "-test.run",
- "MyTestFunction"
- ]
+ "name": "Launch test function",
+ "type": "go",
+ "request": "launch",
+ "mode": "test",
+ "program": "${workspaceFolder}",
+ "args": [
+ "-test.run",
+ "MyTestFunction"
+ ]
}
```
-### Sample configuration to debug all tests in the package
+#### Debug all tests in the given package (`Go: Launch test package`)
-```json
+Recall that `${workspaceFolder}` refers to the current workspace (see [Using VS Code Variables](#using-vs-code-variables)).
+
+```json5
{
- "name": "Launch test package",
- "type": "go",
- "request": "launch",
- "mode": "test",
- "program": "${workspaceFolder}"
+ "name": "Launch test package",
+ "type": "go",
+ "request": "launch",
+ "mode": "test",
+ "program": "${workspaceFolder}"
}
```
-### Sample configuration to debug a pre-built binary
+#### Attach to a running local process via its process ID (`Go: Attach to local process`)
-```json
+Substitute the `0` below for the process ID (pid) of the process.
+
+```json5
{
- "name": "Launch executable",
- "type": "go",
- "request": "launch",
- "mode": "exec",
- "program": "absolute-path-to-the-executable"
+ "name": "Attach to local process",
+ "type": "go",
+ "request": "attach",
+ "mode": "local",
+ "processId": 0
}
```
-### Sample configuration to attach to an already running local process using processId
-Enter the id of the process running your executable in the below snippet
+#### Attach to a running server (`Go: Connect to Server`)
-```json
+```json5
{
- "name": "Attach to local process",
- "type": "go",
- "request": "attach",
- "mode": "local",
- "processId": 0
+ "name": "Connect to server",
+ "type": "go",
+ "request": "attach",
+ "mode": "remote",
+ "remotePath": "${workspaceFolder}",
+ "port": 2345,
+ "host": "127.0.0.1"
}
```
-## Debugging in WSL
+#### Debug an existing binary
-If using WSL on Windows, you will need the WSL 2 Linux kernel. See [WSL 2 Installation](https://docs.microsoft.com/en-us/windows/wsl/wsl2-install) and note the Window 10 build version requirements.
+There is no snippet suggestion for this configuration.
+
+```json
+{
+ "name": "Launch executable",
+ "type": "go",
+ "request": "launch",
+ "mode": "exec",
+ "program": "/absolute/path/to/executable"
+}
+```
+
+## Debugging on [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/)
+
+If you are using using WSL, you will need the WSL 2 Linux kernel. See [WSL 2 Installation](https://docs.microsoft.com/en-us/windows/wsl/wsl2-install) and note the Window 10 build version requirements.
## Remote Debugging
-To remote debug using VS Code, you must first run a headless Delve server on the target machine. The below examples assume
-that you are in the same folder as the package you want to debug. If not, please refer to the [usage doc on dlv debug](https://github.com/go-delve/delve/blob/master/Documentation/usage/dlv_debug.md) command.
+<!--TODO(quoctruong): We use "remote" and "target", as well as "local" here. We should define these terms more clearly and be consistent about which we use.-->
+
+To debug on a remote machine, you must first run a headless Delve server on the target machine. The examples below assume that you are in the same folder as the package you want to debug. If not, please refer to the [`dlv debug` documentation](https://github.com/go-delve/delve/blob/master/Documentation/usage/dlv_debug.md).
+
+To start the headless Delve server:
```bash
-$ dlv debug --headless --listen=:2345 --log --api-version=2
+dlv debug --headless --listen=:2345 --log --api-version=2
```
-Any arguments that you want to pass to the program you are debugging must be passed to this Delve server that runs on the target machine. For example:
+Any arguments that you want to pass to the program you are debugging must also be passed to this Delve server. For example:
```bash
-$ dlv debug --headless --listen=:2345 --log -- -myArg=123
+dlv debug --headless --listen=:2345 --log -- -myArg=123
```
-Then, create a remote debug configuration in VS Code `launch.json`.
+Then, create a remote debug configuration in your `launch.json`.
-```json
+```json5
{
- "name": "Launch remote",
- "type": "go",
- "request": "launch",
- "mode": "remote",
- "remotePath": "absolute-path-to-the-file-being-debugged-on-the-remote-machine",
- "port": 2345,
- "host": "127.0.0.1",
- "program": "absolute-path-to-the-file-on-the-local-machine",
- "env": {}
+ "name": "Launch remote",
+ "type": "go",
+ "request": "launch",
+ "mode": "remote",
+ "remotePath": "/absolute/path/file/on/remote/machine",
+ "port": 2345,
+ "host": "127.0.0.1",
+ "program": "/absolute/path/file/on/local/machine",
+ "env": {}
}
```
-- The above example runs both the headless `dlv` server and the VS Code debugger locally on the same machine. Update `port` and `host` as per your set up on the remote machine instead.
-- `remotePath` should point to the absolute path of the file (in your source code) being debugged in the remote machine
-- `program` should point to the absolute path of the file on your local machine that is the counterpart of the file in `remotePath`
+In the example, the VS Code debugger will run on the same machine as the headless `dlv` server. Make sure to update the `port` and `host` settings to point to your remote machine.
-When you launch the debugger with this new `Launch remote` target selected, VS Code will send debugging
-commands to the `dlv` server you started previously instead of launching it's own `dlv` instance against your app.
+`remotePath` should point to the absolute path of the file being debugged in the remote machine. See [golang/vscode-go#126](https://github.com/golang/vscode-go/issues/126) for updates regarding `remotePath`.
-See the example of debugging a process running in a docker host at https://github.com/lukehoban/webapp-go/tree/debugging.
+`program` should point to the absolute path of the file on your local machine. This should be the counterpart of the file in `remotePath`.
+When you run the `Launch remote` target, VS Code will send debugging commands to the `dlv` server you started, instead of launching it's own `dlv` instance against your app.
+
+For further examples, see [this launch configuration for a process running in a Docker host](https://github.com/lukehoban/webapp-go/tree/debugging).
## Troubleshooting
-If you have issues debugging your Go code, first try to update your version of delve to ensure that you are working with the latest delve and it has been compiled using your current Go version. To do this, run the command `Go: Install/Update Tools`, select `dlv`, press `Ok`.
+Debugging is one of the most complex features offered by this extension. The features are not complete, and a new implementation is currently being developed (see [golang/vscode-go#23](https://github.com/golang/vscode-go/issues/23)).
-### Enabling debug logs
+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).
-- Set `showLog` attribute in your debug configuration to `true`. You will see logs in the debug console from delve.
+### Update Delve
-- Set `trace` attribute in your debug configuration to `log`. You will see logs in the debug console from the Go extension's debug adapter. These logs will be saved to a file whose path will be printed at the beginning in the debug console.
+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`.
-- Set `logOutput` attribute in your debug configuration to `rpc`. You will see logs corresponding to the RPC messages going back and forth between VS Code and delve. Note that this first requires to set `showLog` to `true`.
- - The `logOutput` attribute corresponds to the `--log-output` flag used by delve and can be a comma separated list of components that should produce debug output.
+### Read the Delve documentation
-### Debug the debugger using source code
+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.
-If you want to dig deeper and debug the debugger using source code of this extension, see [building-and-debugging-the-extension](contributing.md#building-and-debugging-the-extension)
+### Enable logging
+
+Next, check the logs produced by Delve. These will need to be manually enabled. Follow these steps:
+
+* Set `"showLog": true` in your launch configuration. This will show Delve logs in the Debug Console pane (Ctrl+Shift+Y).
+* Set `"trace": "log"` in your launch configuration. Again, you will see logs in the Debug Console pane (Ctrl+Shift+Y). These logs will also be saved to a file and the path to this file will be printed at the top of the Debug Console.
+* Set `"logOutput": "rpc"` in your launch configuration. You will see logs of the RPC messages going between VS Code and Delve. Note that for this to work, you must also have set `"showLog": true`.
+ * The `logOutput` attribute corresponds to the `--log-output` flag used by Delve. It is a comma-separated list of components that should produce debug output.
+
+See [common issues](#common-issues) below to decipher error messages you may find in your logs.
+
+With `"trace": "log"`, you will see the actual call being made to `dlv`. To aid in your investigation, you can copy that and run it in your terminal.
+
+### **Optional**: Debug the debugger
+
+This is not a required step, but if you want to continue digging deeper, you can, in fact, debug the debugger. The code for the debugger can be found in the [debug adapter module](../src/debugAdapter). See our [Contribution Guide](contributing.md) to learn how to [run](contributing.md#run) and [sideload](contributing.md#sideload) the Go extension.
+
+### Ask for help
+
+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
-#### Unverified breakpoint or variables not loading when debugging a binary
+#### Unverified breakpoint or variables
-Ensure that the binary being debugged was built with no optimizations. Use the flags `-gcflags="all=-N -l"` when building the binary.
+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 ...
+#### Cannot find package ".." in any of ...
-The debugger is not using the right GOPATH. This shouldn't happen, if it does, log a bug.
+The debugger is not using the right [`GOPATH`](gopath.md). [File an issue report](https://github.com/golang/vscode-go/issues/new/choose).
-**_Solution_**: Until the bug you logged is resolved, the work around is to add the GOPATH as an env var in the `env` property in the `launch.json` file.
+**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 the extension is trying to run the `dlv` binary from a wrong location.
-The Go extension first tries to find `dlv` in your $GOPATH/bin and then in your $PATH.
+You have `dlv` running just fine from command line, but VS Code gives this access-related error.
-**_Solution_**: Run `which dlv` in the command line. If this doesn't match your `GOPATH/bin`, then delete the `dlv` file in
-your `GOPATH/bin`
+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.
+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 when using WSL
-Try running ```delve debug ./main``` at the WSL command line and see if you get a prompt
+#### delve/launch hangs with no messages on WSL
-**_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)
+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)
#### could not launch process: could not fork/exec
-##### OSX
+The solution this issue differs based on your OS.
-This usually happens in OSX due to signing issues. See the discussions in please see [#717](https://github.com/Microsoft/vscode-go/issues/717), [#269](https://github.com/Microsoft/vscode-go/issues/269) and [derekparker/delve/357](https://github.com/derekparker/delve/issues/357)
+##### OSX
-**_Solution_**: You may have to uninstall dlv and install it manually as per [instructions](https://github.com/derekparker/delve/blob/master/Documentation/installation/osx/install.md#manual-install)
+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).
-##### Linux/Docker
+**_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).
-Docker has security settings preventing ptrace(2) operations by default within the container.
+##### Linux/Docker
-**_Solution_**: To run your container insecurely, pass `--security-opt=seccomp:unconfined` to docker run when starting. Reference: [derekparker/delve/515](https://github.com/derekparker/delve/issues/515)
+Docker has security settings preventing `ptrace(2)` operations by default within the container.
+
+**_Solution_**: To run your container insecurely, pass `--security-opt=seccomp:unconfined` to `docker run`. See [derekparker/delve#515](https://github.com/derekparker/delve/issues/515) for references.
#### could not launch process: exec: "lldb-server": executable file not found in $PATH
-This error can show up for Mac users using delve of version 0.12.2 or above. Not sure why, but doing a `xcode-select --install` has solved the problem for users who have seen this issue.
+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 delve api being used in the remote delve process i.e check the value for the flag `–api-version`. This needs to match the version used by the Go extension which uses version 2 by default. You can change the api version being used by the extension by editing the debug configuration in the launch.json file.
-
-#### Try using dlv from the terminal/command-line
-
-Add `"trace": "log"` to your debug configuration and debug in VS Code. This will send logs to the debug console where you can see the actual call being made to dlv. You can copy that and run it in your terminal
+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
diff --git a/docs/features.md b/docs/features.md
index 396cb0a..61991e1 100644
--- a/docs/features.md
+++ b/docs/features.md
@@ -4,9 +4,9 @@
If you are using the Go language server, `gopls`, please the [gopls documentation](gopls.md) instead. (You can check if you are using `gopls` by opening your VS Code settings and checking if `go.useLanguageServer` is set to `true`.)
-If you are using Go modules without the language server, some of the below features will not be available.
+If you are using Go modules *without* the language server, some of the features listed below will not be available.
-Please see the [Tools](tools.md) documentation for details on how to troubleshoot and adjust your settings.
+Please see the [Tools documentation](tools.md) for details on how to troubleshoot and adjust your settings.
## Table of Contents
@@ -27,7 +27,7 @@
* [Add import](#add-import)
* [Rename symbol](#rename-symbol)
* [Code Generation](#code-generation)
- * [Add struct tags](#add-struct-tags)
+ * [Add or remove struct tags](#add-or-remove-struct-tags)
* [Generate interface implementation](#generate-interface-implementation)
* [Generate unit tests](#generate-unit-tests)
* [Fill struct literals](#fill-struct-literals)
@@ -114,7 +114,7 @@
#### Add import
-Manually add a new import to your file through the `Go: Add Import` command.
+Manually add a new import to your file through the `Go: Add Import` command. Available packages are offered from your `GOPATH` and module cache.
### [Rename symbol](https://code.visualstudio.com/docs/editor/refactoring#_rename-symbol)
@@ -126,7 +126,7 @@
## Code Generation
-### Add struct tags
+### Add or remove struct tags
Use the `Go: Add Tags to Struct Fields` command to automatically generate or remove [tags](https://pkg.go.dev/reflect?tab=doc#StructTag) for your struct. This feature is provided by the [`gomodifytags`](tools.md#gomodifytags) tool.
diff --git a/docs/gopath.md b/docs/gopath.md
index f3a7204..7498595 100644
--- a/docs/gopath.md
+++ b/docs/gopath.md
@@ -1,3 +1,5 @@
+# `GOPATH`
+
At any point in time, you can run the command `Go: Current GOPATH` to see the GOPATH being used by the extension.
### GOPATH from the environment variable
diff --git a/docs/modules.md b/docs/modules.md
index 4eeb686..82ec0bd 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -1,3 +1,5 @@
+# Modules
+
The Go language server [gopls](https://golang.org/s/gopls/README.md) provides support for [Go modules](https://blog.golang.org/modules2019).
Add the below in your [settings](https://code.visualstudio.com/docs/getstarted/settings) to use Go modules.
diff --git a/docs/nightly.md b/docs/nightly.md
index 2501b98..e9ff468 100644
--- a/docs/nightly.md
+++ b/docs/nightly.md
@@ -1,20 +1,32 @@
# Go Nightly
-This master branch of this extension is built and published nightly through the [Go Nightly]. If you're interested in testing new features and bug fixes, you may be interested in switching to the Go Nightly extension. Also, if you file an issue, we may suggest trying out the fix in Go Nightly.
+This master branch of this extension is built and published nightly through the [Go Nightly]. If you're interested in testing new features and bug fixes, you may be interested in switching to the [Go Nightly] extension. Also, if you file an issue, we may suggest trying out the fix in [Go Nightly].
-The [Changelog](nightly/CHANGELOG.md) and [README](nightly/README.md) for [Go Nightly] can be found in the [docs/nightly](nightly/) directory.
+[Go Nightly] is the **preview** version of the Go extension, so it may be broken or unstable at times. The [Changelog](nightly/CHANGELOG.md) and [README](nightly/README.md) for [Go Nightly] can be found in the [docs/nightly](nightly/) directory.
-If you try out Go Nightly, please file issues when you notice bugs. You can also join the maintainers in the [#vscode-dev](https://gophers.slack.com/archives/CUWGEKH5Z) channel on the [Gophers Slack](https://invite.slack.golangbridge.org/).
+If you try out [Go Nightly], please file issues when you notice bugs. You can also join the maintainers in the [#vscode-dev](https://gophers.slack.com/archives/CUWGEKH5Z) channel on the [Gophers Slack](https://invite.slack.golangbridge.org/).
## Installation
-To use the Go Nightly extension, you must first disable the standard Go extension. The two are not compatible and will cause conflicts if enabled simultaneously. If you'd like to make a permanent switch, you can uninstall the Go extension. Otherwise, you can disable it temporarily. To do so, open the Extensions view in VS Code, click on the gear icon next to the Go extension, and select Disable. Then, search for Go Nightly in the VS Code Marketplace and install it instead.
+To use the [Go Nightly] extension (`golang.go-nightly`), you **must** first disable the standard Go extension (`golang.Go`) The two are not compatible and will cause conflicts if enabled simultaneously.
+
+If you'd like to make a permanent switch, you can uninstall the Go extension.
+
+Otherwise, you can disable it temporarily. To do so, open the Extensions view in VS Code, click on the gear icon next to the Go extension, and select Disable. Read more in the [documentation on how to disable an extension](https://code.visualstudio.com/docs/editor/extension-gallery#_disable-an-extension).
+
+Once you have uninstalled or disabled the standard Go extension, search for [Go Nightly] in the VS Code Marketplace and install it instead.
+
+## Releases
+
+A new version of [Go Nightly], based on the repository's current [`master` branch](https://go.googlesource.com/vscode-go/+/refs/heads/master), will be released at least once a day between Monday and Thursday. If there are no new commits at master, a new version **will not** be released.
+
+The version number encodes the last commit timestamp of the master branch, with the format `YYYY.[M]M.[D]DHH`. For example, version `2020.3.702` indicates that the extension was built with a final commit merged at ~2AM 2020/03/07 (UTC).
## Testing pre-releases
**Note**: Pre-releases are not yet available.
-Pre-releases of the Go extension will be made available on the [Releases page](https://github.com/golang/vscode-go/releases/tag/latest) on GitHub. If you would like to try a pre-release, follow these instructions:
+Pre-releases of the Go extension will be made available on the [Releases page](https://github.com/golang/vscode-go/releases/tag/latest) on GitHub. These will be separate from the Go Nightly extension. If you would like to try a pre-release, follow these instructions:
1) Download the `.vsix` file from the [Releases page](https://github.com/golang/vscode-go/releases/tag/latest).
2) Navigate to the Extensions view in VS Code (Ctrl+Shift+X). Click on the "..." in the top-right corner, select "Install from VSIX", and select `Go-latest.vsix`. Alternatively, you can run `code --install-extension Go-latest.vsix` or open the Command Palette and run the "Extensions: Install from VSIX..." command.
diff --git a/docs/settings.md b/docs/settings.md
new file mode 100644
index 0000000..d8b63ec
--- /dev/null
+++ b/docs/settings.md
@@ -0,0 +1,64 @@
+# Settings
+
+This extension is highly configurable, and as such, offers a number of settings. These can be configured by modifying your [User or Workspace Settings](https://code.visualstudio.com/docs/getstarted/settings). To navigate to your settings, open the Command Palette (Ctrl+Shift+P) and search for "settings". The simplest way to modify your settings is through "Preferences: Open Settings (UI)".
+
+**NOTE: Many of these settings don't apply if you are using [`gopls`](gopls.md). Learn more about `gopls`-specific settings in this [documentation](https://github.com/golang/tools/blob/master/gopls/doc/settings.md).**
+
+## Latest changes
+
+The settings described below are up-to-date as of June 2020. We do our best to keep documentation current, but if a setting is missing, you can always consult the full list in the Extensions view. Documentation for each setting should also be visible in the Settings UI.
+
+To view the list of settings:
+
+1. Navigate to the Extensions view (Ctrl+Shift+X).
+2. Find the Go extension and click on it to open the Extension Editor.
+3. Click on the `Feature Contributions` tab.
+4. Scroll through the list under `Settings`.
+
+## Detailed list
+
+A list of popular and notable settings can be found below.
+
+* [docsTool](#docsTool)
+* [formatTool](#formatTool)
+* [lintTool](#lintTool)
+* [lintFlags](#lintFlags)
+
+### docsTool
+
+One of `"godoc"`, `"gogetdoc"`, or `"guru"` (`gogetdoc` is the default). This is the tool used by the [go to definition](features.md#go-to-definition), [signature help](features.md#signature-help), and [quick info on hover](features.md#quick-info-on-hover) features. See more information about each of these tools in the [Documentation](tools.md#Documentation) section.
+
+### formatTool
+
+One of `"gofmt"`, `"goimports"`, `"goreturns"`, and `"goformat"` (`goreturns` is the default). This is the tool used by the [formatting and import organization](features.md#formatting-and-import-organization) features. See more information about each of these tools in the [Formatting](tools.md#Formatting) section.
+
+### lintTool
+
+One of `"golint"`, `"staticcheck"`, `"golangci-lint"`, and `"revive"` (`golint` is the default). This is the tool used by the [lint-on-save](features.md#lint-on-save) feature. See more information about each of these tools in the [Diagnostics](tools.md#Diagnostics) section.
+
+### lintFlags
+
+This setting can be used to pass additional flags to your lint tool of choice.
+
+Most linters can be configured via special configuration files, but you may still need to pass command-line flags. The configuration documentation for each supported linter is listed here:
+
+* [`staticcheck`](https://staticcheck.io/docs/#configuration)
+* [`golangci-lint`](https://golangci-lint.run/usage/configuration/)
+* [`revive`](https://github.com/mgechev/revive#command-line-flags)
+
+#### Examples
+
+Enable all [`golangci-lint`] linters and only show errors in new code:
+
+```json5
+"go.lintFlags": ["--enable-all", "--new"]
+```
+
+Configure `revive` to exclude `vendor` directories and apply extra configuration with a `config.toml` file:
+
+```json5
+"go.lintFlags": [
+ "-exclude=vendor/...",
+ "-config=${workspaceFolder}/config.toml"
+]
+```
diff --git a/docs/tasks.md b/docs/tasks.md
index e85f52e..4aa9ea2 100644
--- a/docs/tasks.md
+++ b/docs/tasks.md
@@ -1,4 +1,4 @@
-## How do I use VS Code's "Tasks" with Go?
+# Using [VS Code Tasks](https://code.visualstudio.com/docs/editor/tasks) with Go
Invoke `Tasks: Configure Task Runner` from the command palette.
diff --git a/docs/testing.md b/docs/testing.md
new file mode 100644
index 0000000..b9f28ae
--- /dev/null
+++ b/docs/testing.md
@@ -0,0 +1,43 @@
+# Testing
+
+We currently use two separate continuous integration (CI) systems to test all changes and pushed commits:
+
+* [Tests running in Google Cloud Build (GCB)](#testing-via-gcb), and
+* [Tests running with GitHub Actions](#testing-via-github-actions)
+
+This is a temporary setup; once GCB fully supports our desired workflow, we plan to use only the GCB-based setup for CI.
+
+## Testing via GCB
+
+This workflow is triggered for Gerrit CLs and for all commits merged into the master branch. Note that our main repository is [go.googlesource.com/vscode-go](https://go.googlesource.com/vscode-go), and
+[github.com/golang/vscode-go](https://github.com/golang/vscode-go) is a mirror of the Go Git repository. All PRs sent to the GitHub repository will be converted to Gerrit CLs.
+
+Currently, the results of the CI run are visible only to GCB project members. We are working on improving this workflow and making the results visible to the public and easily accessible through our Gerrit review UI.
+
+The GCB workflow is defined in [`build/cloudbuild.yaml`](../build/cloudbuild.yaml) and [`build/all.bash`](../build/all.bash).
+
+The Docker container used for testing is defined in [`build/cloudbuild.container.yaml`](../build/cloudbuild.container.yaml) and [`build/Dockerfile`](../build/Dockerfile).
+
+GCB project members can manually trigger a build and test their local changes. Follow the [GCB instructions](https://cloud.google.com/cloud-build/docs/running-builds/start-build-manually) to set up the environment and tools, and then run:
+
+```bash
+gcloud builds submit --config=build/cloudbuild.yaml
+```
+
+In order to modify and rebuild the Docker container image, run:
+
+```bash
+gcloud builds submit --config=build/cloudbuild.container.yaml
+```
+
+## Testing via GitHub Actions
+
+This is the workflow triggered for every PR and commit made to our mirror repository on GitHub, [github.com/golang/vscode-go](https://github.com/golang/vscode-go). We use this CI system to run tests on platforms that GCB does not yet support. This workflow is not triggered by CLs sent via Gerrit yet.
+
+[`.github/workflows/ci.yml`](../.github/workflows/ci.yml) defines the GitHub Actions-based CI workflow.
+
+### [Nightly Release](nightly.md)
+
+A new version of the [Go Nightly](nightly.md) extension, based on the current `master` branch, is released at least once a day between Monday and Thursday. Learn more in the [Go Nightly documentation](nightly.md).
+
+The daily release process is automated via a GitHub Action. See [`.github/workflows/release.yml`](../.github/workflows/release.yml) and [`build/all.bash`](../build/all.bash).
diff --git a/docs/tools.md b/docs/tools.md
index 98d4ef6..91e9acd 100644
--- a/docs/tools.md
+++ b/docs/tools.md
@@ -108,7 +108,7 @@
### [`gomodifytags`](https://pkg.go.dev/github.com/fatih/gomodifytags?tab=overview)
-This tool provides support for the [`Go: Add Tags to Struct Fields`](features.md#add-struct-tags) command.
+This tool provides support for the [`Go: Add Tags to Struct Fields`](features.md#add-or-remove-struct-tags) and [`Go: Remove Tags From Struct Fields`](features.md#add-or-remove-struct-tags) commands.
### [`impl`](https://github.com/josharian/impl)
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 0000000..2c1b77c
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,3 @@
+# Troubleshooting
+
+[Troubleshooting Debugging](debugging.md#troubleshooting)
\ No newline at end of file
