[release] docs: rewrite contributions and beta testing guides
From https://golang.org/cl/234535 authored by Rebecca Stambler (rstambler@golang.org)
This change updates the contribution guide to explain the Go contribution guidelines. https://golang.org/doc/contribute.html still needs to be generalized to all x/ repos, so that will be done in a separate change.
Also, change beta.md into nightly.md and explain the Go Nightly extension.
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/234535
Reviewed-by: Hyang-Ah Hana Kim <hyangah@gmail.com>
(cherry picked from commit a745aaf37de8857827c2cfd01ca48b3c7a22b0ee)
Change-Id: I0f4a218d4b23575079e376de0165ca44cb8a40fb
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/236743
Reviewed-by: Rebecca Stambler <rstambler@golang.org>
diff --git a/docs/beta.md b/docs/beta.md
deleted file mode 100644
index 36c2842..0000000
--- a/docs/beta.md
+++ /dev/null
@@ -1,7 +0,0 @@
-If you ever want to try the beta version of the Go extension which is built from the master, follow the below instructions:
-
-- Download the vsix file from https://github.com/Microsoft/vscode-go/releases/tag/latest
-- Run `code --install-extension Go-latest.vsix`
-- Reload VS Code
-
-**Note**: When when you install a beta version, there is no auto-update mechanism where a newer beta version will get installed automatically.
diff --git a/docs/commands.md b/docs/commands.md
index 7723246..5647d8f 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -1,12 +1,15 @@
-You can view the Visual Studio Code settings for the Go extension along with their *default* values and description in the product itself
+# Settings and Commands
-1. Press `Ctrl+Shift+X` or `Cmd+Shift+X` to open the Extensions viewlet.
+To view a complete list of the commands settings for this extension:
+
+1. Navigate to the Extensions view (Ctrl+Shift+X).
2. Find the Go extension, click on it to open the Extension Editor.
-3. Click on the `Contributions` tab.
+3. Click on the `Feature Contributions` tab.
4. Scroll away.
+<!--TODO(rstambler): This image needs to be updated.-->
-If you want to change any of these, you can do so in user preferences (`cmd+,` or `ctrl+,`) or workspace settings (`.vscode/settings.json`). You don't have to copy these if you don't intend to change them.
+## Settings
-Scroll down and you will see list of all available commands with description too
\ No newline at end of file
+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)".
diff --git a/docs/contributing.md b/docs/contributing.md
index 9ff2903..115f4a2 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -1,42 +1,96 @@
-You can set up a development environment for debugging the extension during extension development.
+# Contributing
-## Building and Debugging the extension
+We welcome your contributions and thank you for working to improve the Go development experience in VS Code.
-Ensure you have [node](https://nodejs.org/en/) installed.
-Clone the repo, run `npm install` and open a development instance of Code.
+This guide will explain the process of setting up your development environment to work on the VS Code Go extension, as well as the process of sending out your change for review. If you're interested in testing the master branch or pre-releases of the extension, please see the [Go Nightly documentation](nightly.md).
-```bash
-git clone https://github.com/Microsoft/vscode-go
-cd vscode-go
-npm install
-code .
-```
+* [Before you start coding](#before-you-start-coding)
+ * [Ask for help](#ask-for-help)
+* [Developing](#developing)
+ * [Setup](#setup)
+ * [Run](#run)
+ * [Test](#test)
+ * [Sideload](#sideload)
+* [Mail your change for review](#mail-your-change-for-review)
-Make sure the `window.openFoldersInNewWindow` setting is not `"on"`.
+## Before you start coding
-You can now go to the Debug viewlet (`Ctrl+Shift+D`) and select `Launch Extension` then hit run (`F5`).
+If you are interested in fixing a bug or contributing a feature, please [file an issue](https://github.com/golang/vscode-go/issues/new/choose) first. Wait for a project maintainer to respond before you spend time coding.
-This will open a new VS Code window which will have the title `[Extension Development Host]`. In this window, open any folder with Go code.
+If you wish to work on an existing issue, please add a comment saying so, as someone may already be working on it. A project maintainer may respond with advice on how to get started. If you're not sure which issues are available, search from issues with the [help wanted label](https://github.com/golang/vscode-go/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22).
-In the original VS Code window, you can now add breakpoints which will be hit when you use any of the the plugin's features in the second window.
+### Ask for help
-If you make edits in the extension `.ts` files, just reload (`cmd-r`) the `[Extension Development Host]` instance of Code to load in the new extension code. The debugging instance will automatically reattach.
+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.
-To debug the debugger, see [the debugAdapter readme](/Microsoft/vscode-go/tree/master/src/debugAdapter).
+## Developing
-## Running the tests
-To run the tests locally, open the Debug viewlet (`Ctrl+Shift+D`), select `Launch Tests`, then hit run (`F5`)
+### Setup
-## Sideloading the extension
-After making changes to the extension, you might want to test it end to end instead of running it in debug mode. To do this, you can sideload the extension. This can be done by preparing the extension and loading it directly.
+1) Install [node](https://nodejs.org/en/).
+2) Clone the repository, run `npm install` and open VS Code:
-1. `npm install -g vsce` to make sure you have vsce installed globally
-2. `git clone https://github.com/Microsoft/vscode-go` to clone the repo if you havent already done so
-3. `cd vscode-go`
-4. `npm install` to install dependencies if you havent already done so
-5. `vsce package` to build the package. This will generate a file with extension `vsix`
-6. Run the command `Extensions: Install from VSIX...`, choose the vsix file generated in the previous step
+ ```bash
+ git clone https://github.com/golang/vscode-go
+ cd vscode-go
+ npm install
+ code .
+ ```
-## Use the beta version of this extension
+3) Make sure the `window.ope
+nFoldersInNewWindow` setting is not `"on"`. <!--TODO(rstambler): Confirm that this is still required.-->
-If you want to help with testing the next update to this extension or you want to use the latest features that arent released yet, its easy to do so. Please see [Use the beta version of the Go extension](beta.md).
\ No newline at end of file
+### Run
+
+To run the extension with your patch, open the Run view (`Ctrl+Shift+D`), select `Launch Extension`, and click the Play button (`F5`).
+
+This will open a new VS Code window with the title `[Extension Development Host]`. You can then open a folder that contains Go code and try out your changes.
+
+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`).
+
+## Sideload
+
+After making changes to the extension, you may want to test it end-to-end instead of running it in debug mode. To do this, you can sideload the extension.
+
+1. Install the [vsce](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#vsce) tool for packaging extensions (`npm install -g vsce`).
+2. `cd` into your `vscode-go` directory.
+3. Install all dependencies by running `npm install`.
+4. Run `vsce package` to build the package. This will generate a file with a `.vsix` extension in your current directory.
+
+ ```bash
+ npm install -g vsce
+ cd vscode-go
+ npm install
+ vsce package
+ ```
+
+5. Open a VS Code window, navigate to the Extensions view, and disable or uninstall the default Go extension.
+6. Click on the "..." in the top-right corner, select "Install
+from VSIX...", and choose the generated VSIX file. Alternatively, you can run `code --install-extension path/to/go.vsix` or open the Command Palette and run the "Extensions: Install from VSIX..." command.
+
+## Mail your change for review
+
+Once you have coded, built, and tested your change, it's ready for review! There are two ways to contribute your change: (1) [a GitHub pull request (PR)](https://golang.org/doc/contribute.html#sending_a_change_github), or (2) a [Gerrit code review](https://golang.org/doc/contribute.html#sending_a_change_gerrit).
+
+<!--TODO(rstambler): The content on https://golang.org/doc/contribute.html needs to be generalized to all x/ repos.-->
+
+In either case, code review will happen in [Gerrit](https://www.gerritcodereview.com/), which is used for all repositories in the Go project. GitHub pull requests will be mirrored into Gerrit, so you can follow a more traditional GitHub workflow, but you will still have to look at Gerrit to read comments.
+
+The easiest way to start is by reading this [detailed guide for contributing to the Go project](https://golang.org/doc/contribute.html). Important things to note are:
+
+* You will need to sign the [Google CLA](https://golang.org/doc/contribute.html#cla).
+* Your commit message should follow the standards described on the [Commit Message Wiki page](https://github.com/golang/go/wiki/CommitMessage).<!--TODO(rstambler): What should the prefix be for vscode-go CLs? I feel like we still haven't figured this out.-->
+* Your change should include tests (if possible).
+
+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].
+
+[#vscode-dev]: https://gophers.slack.com/archives/CUWGEKH5Z
+[Gophers Slack]: https://invite.slack.golangbridge.org/
diff --git a/docs/nightly.md b/docs/nightly.md
new file mode 100644
index 0000000..776b2f4
--- /dev/null
+++ b/docs/nightly.md
@@ -0,0 +1,21 @@
+# Go Nightly
+
+This master branch of this extension is built and published nightly through the [Go Nightly](https://marketplace.visualstudio.com/items?itemName=golang.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.
+
+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.
+
+## 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:
+
+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.
+3) If prompted, reload VS Code.
+
+**Note**: If you install an extension from a VSIX file, you will stop receiving automatic prompts when updates are released.
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index b642e0b..85836ab 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -118,4 +118,4 @@
**Q: How do I get the features/bug fixes that are implemented but not released yet? How do I get the beta version of the Go extension?**
-**A:** See [Install the beta version](beta.md).
\ No newline at end of file
+**A:** Install the [Go Nightly](nightly.md) extension.
