README: add troubleshooting section, some cleanup
Change-Id: I92cd750dcfb393bf7cd33257f02d8d57c369f534
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/286472
Trust: Rebecca Stambler <rstambler@golang.org>
Run-TryBot: Rebecca Stambler <rstambler@golang.org>
Reviewed-by: Hyang-Ah Hana Kim <hyangah@gmail.com>
diff --git a/README.md b/README.md
index 98010c8..0533016 100644
--- a/README.md
+++ b/README.md
@@ -8,12 +8,6 @@
provides rich language support for the
[Go programming language](https://golang.org/).
-> 📣 We will enable the language server ([`gopls`]) by default in the end of Jan
-> 2021. We recommend switching to the language server now
-> (`"go.useLanguageServer": true`) to confirm it works well for you. Please
-> [file a new issue](https://github.com/golang/vscode-go/issues/new/choose) if
-> you notice bugs or missing features.
-
## Quick Start
Welcome! 👋🏻<br/>
@@ -23,7 +17,7 @@
* **Step 1.** If you haven't done so already, install [Go](https://golang.org)
and the [VS Code Go extension].
* [Go installation guide]. This extension works best with Go 1.14+.
- * [Manage extensions in VS Code].
+ * [Managing extensions in VS Code].
* **Step 2.** To activate the extension, open any directory or workspace
containing Go code. Once activated, the [Go status bar](docs/ui.md) will
appear in the bottom left corner of the window and show the recognized Go
@@ -40,23 +34,23 @@
You are ready to Go :-) 🎉🎉🎉
-Please be sure to learn more about many [features](#features) of this extension
-as well as how to [customize](#customization) them. Take a look at
+Please 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 [Help](#ask-for-help) for further
guidance.
If you are new to Go, [this article](https://golang.org/doc/code.html) provides
-the overview on go code organization and basic `go` commands. The recent
-[Go open source live video] featured VS Code Go and demonstrated how other
-Gophers use the features to enhance their Go development workflow.
+the overview on Go code organization and basic `go` commands. Watch [this video
+from the Go Open Source Live conference] for an explanation of how to build
+your first Go application using VS Code Go.
## Features
This extension provides many features, including [IntelliSense],
-[code navigation], [code editing] support. It also shows [diagnostics] as you
-work and provides enhanced support for [testing] and [debugging] your programs.
-See the [full feature breakdown] for more details and to learn how to tune the
-behavior.
+[code navigation], and [code editing] support. It also shows [diagnostics] as
+you work and provides enhanced support for [testing] and [debugging] your
+programs. See the [full feature breakdown] for more details and to learn how to
+tune its behavior.
<p align=center>
<img src="docs/images/completion-signature-help.gif" width=75%>
@@ -68,33 +62,31 @@
commands for working with Go files. You can access any of these by opening the
Command Palette (`Ctrl+Shift+P` on Linux/Windows and `Cmd+Shift+P` on Mac), and
then typing in the command name. See the
-[full list of commands](docs/commands.md#detailed-list) provided by the
+[full list of commands](docs/commands.md#detailed-list) provided by this
extension.
<p align=center>
<img src="docs/images/toggletestfile.gif" width=75%>
<br/><em>(Toggle Test File)</em></p>
-**⚠️ Note**: the default syntax highlighting for Go files is provided by the
+**⚠️ Note**: the default syntax highlighting for Go files is provided by a
[TextMate rule](https://github.com/jeff-hykin/better-go-syntax) embedded in VS
Code, not by this extension.
## Tools
The extension uses a few command-line tools developed by the Go community. In
-particular, `go`, `gopls`, and `dlv` are used to implement build/test, language
-features, and debugging functionalities of this extension. See the
-[tools documentation](docs/tools.md) for a complete list of tools the extension
-depends on.
+particular, `go`, `gopls`, and `dlv` **must** be installed for this extension
+to work correctly. See the [tools documentation](docs/tools.md) for a complete
+list of tools the extension depends on.
-In order to locate the command-line tools, the extension searches `$GOPATH/bin`
-and directories specified in the `PATH` environment variable (or `Path` in
-Windows) with which the VS Code process has started. If the tools are not found,
-the extension will prompt you to install the missing tools and show the "⚠️
-Analysis Tools Missing" warning in the bottom right corner. Please install them
-by responding to the warning notification, or by manually running the `Go:
-Install/Update Go Tools` command. The extension will run the
-[`go get`](https://golang.org/cmd/go) command to install them.
+In order to locate these command-line tools, the extension searches
+`GOPATH/bin` and directories specified in the `PATH` environment variable (or
+`Path` on Windows) with which the VS Code process has started. If the tools are
+not found, the extension will prompt you to install the missing tools and show
+the "⚠️ Analysis Tools Missing" warning in the bottom right corner. Please
+install them by responding to the warning notification, or by manually running
+the [`Go: Install/Update Go Tools` command].
## Setting up your workspace
@@ -102,34 +94,43 @@
recent versions of Go. Modules replace the `GOPATH`-based approach to specifying
which source files are used in a given build, and they are the default build
mode in go1.16+. While this extension continues to support both Go modules and
-`GOPATH` mode, we highly recommend Go development in module mode. If you are
+`GOPATH` modes, we highly recommend Go development in module mode. If you are
working on existing projects, please consider migrating to modules.
Unlike the traditional `GOPATH` mode, module mode does not require the workspace
to be located under `GOPATH` nor to use a specific structure. A module is
defined by a directory tree of Go source files with a `go.mod` file in the
-tree's root directory. Your project may involve one or more modules. If you are
-working with multiple modules or uncommon project layouts, you will need to
-configure your workspace so that the extension knows which code to load, so that
-features like references can work across modules. Please see the
-for information on supported workspace layouts.
+tree's root directory.
+
+Your project may involve one or more modules. If you are working with multiple
+modules or uncommon project layouts, you will need to configure your workspace
+by using [Workspace Folders]. Please see this [documentation about supported
+workspace layouts].
## Customization
The extension needs no configuration and should work out of the box. However,
-you may wish to adjust settings to customize its behavior. Below are a few
-commonly used settings. Please see the
+you may wish to adjust settings to customize its behavior. Please see the
[settings documentation](docs/settings.md) for a comprehensive list of settings.
See [advanced topics](docs/advanced.md) for further customizations and unique
use cases.
+## Troubleshooting
+
+If the extension isn't working as you expect, you can take a look at our
+troubleshooting guides. There is one for [general
+troubleshooting](docs/troubleshooting.md), and another specifically for
+[troubleshooting the debugging feature](docs/debugging.md#troubleshooting).
+
## 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!
+If the troubleshooting guides did not resolve the issue, please reach out to us
+by [filing an issue](https://github.com/golang/vscode-go/issues/new/choose),
+[starting a GitHub discussion](https://github.com/golang/vscode-go/discussions),
+or by asking a question in the [Gophers Slack]. We hang out in the `#vscode`
+channel!
-Take a look at [learn.go.dev](https://learn.go.dev) and
+Also, you can take a look at [learn.go.dev](https://learn.go.dev) and
[golang.org/help](https://golang.org/help) for more general guidance on using
Go.
@@ -160,10 +161,10 @@
[Gophers Slack]: https://gophers.slack.com/
[`gopls`]: https://golang.org/s/gopls
[`go`]: https://golang.org/cmd/go
-[Manage extensions in VS Code]: https://code.visualstudio.com/docs/editor/extension-gallery
+[Managing extensions in VS Code]: https://code.visualstudio.com/docs/editor/extension-gallery
[VS Code Go extension]: https://marketplace.visualstudio.com/items?itemName=golang.go
[Go installation guide]: https://golang.org/doc/install
-[Go open source live video]: https://opensourcelive.withgoogle.com/events/go/watch?talk=session3
+[this video from the Go Open Source Live conference]: https://opensourcelive.withgoogle.com/events/go/watch?talk=session3
[IntelliSense]: docs/features.md#intellisense
[code navigation]: docs/features.md#code-navigation
[code editing]: docs/features.md#code-editing
@@ -172,3 +173,6 @@
[debugging]: #debugging
[full feature breakdown]: docs/features.md
[workspace documentation]: https://github.com/golang/tools/blob/master/gopls/doc/workspace.md
+[`Go: Install/Update Go Tools` command]: docs/commands.md#go-installupdate-tools
+[documentation about supported workspace layouts]: https://github.com/golang/tools/blob/master/gopls/doc/workspace.md
+[Workspace Folders]: https://code.visualstudio.com/docs/editor/multi-root-workspaces
