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

Author: stamblerre

build/Dockerfile

@@ -1,3 +1,5 @@
+# This Docker container is used for testing on GCB.
+
 FROM golang:1.14 AS gobuilder
 
 ENV GO111MODULE on

build/README.md

@@ -0,0 +1 @@
+# See the [testing documentation](../docs/testing.md)

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**
-
-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.
-
-**Features to Smoke Test:**
-
-Try the below features for functions, structs and interfaces from current/std/third party packages
-- Goto and Peek Definition 
-- Find References 
-- Hover Info 
-
-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 
-
-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
-
-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
-
-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
-
-Other features:
-- File outline 
-- Debugging 
+# 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.-->

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`.
+
+Finally, you can also see a full list by using a meta command: `Go: Show All Commands...`.
+
+## Detailed list
+
+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)).
+
+### Code editing and generation
+
+<!--Note: Try to keep this list in roughly alphabetical/logical order.-->
+
+#### [`Go: Add Import`](features.md#add-import)
+
+<!--TODO(rstambler): Confirm exactly how this works.-->
+Manually add an import to your file. See [Add import](features.md#add-import).
+
+#### [`Go: Add Package to Workspace`]()
+
+#### [`Go: Add Tags to Struct Fields`](features.md#add-struct-tags)
+
+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).
+
+#### [`Go: Remove Tags From Struct Fields`](features.md#add-struct-tags)
+
+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).
+
+#### [`Go: Fill struct`](features.md#fill-struct-literals)
+
+Fill a struct literal with default values. See [Fill struct](features.md#fill-struct-literals).
+
+#### [`Go: Generate Interface Stubs`](features.md#generate-interface-implementation)
+
+Generate method stubs for given interface. See [Generate interface implementation](features.md#generate-interface-implementation).
+
+#### [`Go: Generate Unit Tests For Function`](features.md#generate-unit-tests)
+
+Generate unit tests for the selected function in the current file. See [Generate unit tests](features.md#generate-unit-tests).
+
+#### [`Go: Generate Unit Tests For File`](features.md#generate-unit-tests)
+
+Generate unit tests for the current file. See [Generate unit tests](features.md#generate-unit-tests).
+
+#### [`Go: Generate Unit Tests For Package`](features.md#generate-unit-tests)
+
+Generate unit tests for the current package. See [Generate unit tests](features.md#generate-unit-tests).
+
+#### [`Go: Extract to function`]()
+
+#### [`Go: Extract to variable`]()
+
+### 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)
 
-<!--TODO(rstambler): This image needs to be updated.-->
-![ext](https://user-images.githubusercontent.com/16890566/30246497-9d6cc588-95b0-11e7-87dd-4bd1b18b139f.gif)
+Re-run the most recently executed test command.
 
-## Settings
+#### [`Go: Test All Packages In Workspace`](features.md#test-and-benchmark-in-the-editor)
 
-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)".
+Run all of the tests in the current workspace.
 
-**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).**
+#### [`Go: Cancel Running Tests]()
 
-A list of popular and notable settings can be found below.
+#### [`Go: Toggle Test File`]()
 
-### docsTool
+#### [`Go: Apply Cover Profile]()
 
-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.
+#### [`Go: Toggle Test Coverage In Current Package`]()
 
-### formatTool
+### Build, lint, and vet
 
-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: Build Current Package`]()
 
-### lintTool
+#### [`Go: Lint Current Package`]()
 
-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: Vet Current Package`]()
 
-### lintFlags
+#### [`Go: Build Workspace`]()
 
-This setting can be used to pass additional flags to your lint tool of choice.
+#### [`Go: Lint Workspace`]()
 
-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:
+#### [`Go: Vet Workspace`]()
 
-* [`staticcheck`](https://staticcheck.io/docs/#configuration)
-* [`golangci-lint`](https://golangci-lint.run/usage/configuration/)
-* [`revive`](https://github.com/mgechev/revive#command-line-flags)
+#### [`Go: Install Current Package`]()
 
-#### Examples
+### Miscellaneous
 
-Enable all [`golangci-lint`] linters and only show errors in new code:
+#### [`Go: Restart Language Server`]()
 
-```json5
-"go.lintFlags": ["--enable-all", "--new"]
-```
+#### [`Go: Run on Go Playground`](features.md#go-playground)
 
-Configure `revive` to exclude `vendor` directories and apply extra configuration with a `config.toml` file:
+Upload the current selection or file to the Go Playground ([play.golang.org](https://play.golang.org)). See [Go Playground](features.md#go-playground).
 
-```json5
-"go.lintFlags": [
-    "-exclude=vendor/...",
-    "-config=${workspaceFolder}/config.toml"
-]
-```
+### Troubleshooting
 
-### Commands
+#### `Go: Current GOPATH`
 
-In addition to integrated editing features, the extension also provides several commands in the Command Palette for working with Go files:
+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: 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: Install/Update Tools`](tools.md)
 
-You can access all of the above commands from the command palette (`Cmd+Shift+P` or `Ctrl+Shift+P`).
+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.
 
-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`.
+#### [`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
+[`revive`]: https://pkg.go.dev/github.com/mgechev/revive?tab=overview
+[`gomodifytags`]: tools.md#gomodifytags

docs/contributing.md

@@ -92,5 +92,9 @@ The easiest way to start is by reading this [detailed guide for contributing to
 
 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/