doc: update contribution guide to make it friendlier for x/ repos

The current contributor documentation is tailored towards contributors
to golang/go, but we have a number of increasingly popular x/ repos.
In this CL, I tried to generalize the language to make it apply to any
repository.

Also, I fixed an old link I noticed in editors.html.

Change-Id: Id9d8e448262ed8c3a67f49be5d554ca29df9d3c1
Reviewed-on: https://go-review.googlesource.com/c/go/+/234899
Run-TryBot: Rebecca Stambler <rstambler@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
Reviewed-by: Hyang-Ah Hana Kim <hyangah@gmail.com>

2 files changed, 108 insertions, 34 deletions

diff --git a/doc/contribute.html b/doc/contribute.html
index 5fefac6bba..6188ee197b 100644
--- a/doc/contribute.html
+++ b/doc/contribute.html
@@ -263,6 +263,24 @@ a new issue</a> or by claiming
 an <a href="https://golang.org/issues">existing one</a>.
 </p>
 
+<h3 id="where">Where to contribute</h3>
+
+<p>
+The Go project consists of the main
+<a href="https://go.googlesource.com/go">go</a> repository, which contains the
+source code for the Go language, as well as many golang.org/x/... repostories.
+These contain the various tools and infrastructure that support Go. For
+example, <a href="https://go.googlesource.com/pkgsite">golang.org/x/pkgsite</a>
+is for <a href="https://pkg.go.dev">pkg.go.dev</a>,
+<a href="https://go.googlesource.com/playground">golang.org/x/playground</a>
+is for the Go playground, and
+<a href="https://go.googlesource.com/tools">golang.org/x/tools</a> contains
+a variety of Go tools, including the Go language server,
+<a href="https://golang.org/s/gopls">gopls</a>. You can see a
+list of all the golang.org/x/... repositories on
+<a href="https://go.googlesource.com">go.googlesource.com</a>.
+</p>
+
 <h3 id="check_tracker">Check the issue tracker</h3>
 
 <p>
@@ -273,6 +291,13 @@ Issues are triaged to categorize them and manage the workflow.
 </p>
 
 <p>
+The majority of the golang.org/x/... repos also use the main Go
+issue tracker. However, a few of these repositories manage their issues
+separately, so please be sure to check the right tracker for the repository to
+which you would like to contribute.
+</p>
+
+<p>
 Most issues will be marked with one of the following workflow labels:
 </p>
 
@@ -329,11 +354,16 @@ the code review tool is not the place for high-level discussions.
 
 <p>
 When planning work, please note that the Go project follows a <a
-href="https://golang.org/wiki/Go-Release-Cycle">six-month development cycle</a>.
-The latter half of each cycle is a three-month feature freeze during
-which only bug fixes and documentation updates are accepted.
-New contributions can be sent during a feature freeze, but they will
-not be merged until the freeze is over.
+href="https://golang.org/wiki/Go-Release-Cycle">six-month development cycle</a>
+for the main Go repository. The latter half of each cycle is a three-month
+feature freeze during which only bug fixes and documentation updates are
+accepted. New contributions can be sent during a feature freeze, but they will
+not be merged until the freeze is over. The freeze applies to the entire main
+repository as well as to the code in golang.org/x/... repositories that is
+needed to build the binaries included in the release. See the lists of packages
+vendored into
+<a href="https://github.com/golang/go/blob/master/src/vendor/modules.txt">the standard library</a>
+and the <a href="https://github.com/golang/go/blob/master/src/cmd/vendor/modules.txt"><code>go</code> command</a>.
 </p>
 
 <p>
@@ -408,13 +438,29 @@ This is an overview of the overall process:
 
 <ul>
 <li>
-<b>Step 1:</b> Clone the Go source code from <code>go.googlesource.com</code>
-and make sure it's stable by compiling and testing it once:
+<b>Step 1:</b> Clone the source code from <code>go.googlesource.com</code> and
+make sure it's stable by compiling and testing it once.
+
+<p>If you're making a change to the
+<a href="https://go.googlesource.com/go">main Go repository</a>:</p>
+
 <pre>
 $ git clone https://go.googlesource.com/go
 $ cd go/src
 $ ./all.bash                                # compile and test
 </pre>
+
+<p>
+If you're making a change to one of the golang.org/x/... repositories
+(<a href="https://go.googlesource.com/tools">golang.org/x/tools</a>,
+in this example):
+</p>
+
+<pre>
+$ git clone https://go.googlesource.com/tools
+$ cd tools
+$ go test ./...                             # compile and test
+</pre>
 </li>
 
 <li>
@@ -434,10 +480,18 @@ $ [etc.]
 </li>
 
 <li>
-<b>Step 3:</b> Test your changes, re-running <code>all.bash</code>.
+<b>Step 3:</b> Test your changes, either by running the tests in the package
+you edited or by re-running <code>all.bash</code>.
+
+<p>In the main Go repository:</p>
 <pre>
 $ ./all.bash    # recompile and test
 </pre>
+
+<p>In a golang.org/x/... repository:</p>
+<pre>
+$ go test ./... # recompile and test
+</pre>
 </li>
 
 <li>
@@ -465,7 +519,7 @@ The rest of this section describes these steps in more detail.
 </p>
 
 
-<h3 id="checkout_go">Step 1: Clone the Go source code</h3>
+<h3 id="checkout_go">Step 1: Clone the source code</h3>
 
 <p>
 In addition to a recent Go installation, you need to have a local copy of the source
@@ -475,11 +529,19 @@ you want as long as it's outside your <code>GOPATH</code>.
 Clone from <code>go.googlesource.com</code> (not GitHub):
 </p>
 
+<p>Main Go repository:</p>
 <pre>
 $ git clone https://go.googlesource.com/go
 $ cd go
 </pre>
 
+<p>golang.org/x/... repository</p>
+(<a href="https://go.googlesource.com/tools">golang.org/x/tools</a> in this example):
+<pre>
+$ git clone https://go.googlesource.com/tools
+$ cd tools
+</pre>
+
 <h3 id="make_branch">Step 2: Prepare changes in a new branch</h3>
 
 <p>
@@ -543,9 +605,13 @@ into a single one.
 <p>
 You've <a href="code.html">written and tested your code</a>, but
 before sending code out for review, run <i>all the tests for the whole
-tree</i> to make sure the changes don't break other packages or programs:
+tree</i> to make sure the changes don't break other packages or programs.
 </p>
 
+<h4 id="test-gorepo">In the main Go repository</h4>
+
+<p>This can be done by running <code>all.bash</code>:</p>
+
 <pre>
 $ cd go/src
 $ ./all.bash
@@ -574,6 +640,33 @@ See also
 the section on how to <a href="#quick_test">test your changes quickly</a>.
 </p>
 
+<h4 id="test-xrepo">In the golang.org/x/... repositories</h4>
+
+<p>
+Run the tests for the entire repository
+(<a href="https://go.googlesource.com/tools">golang.org/x/tools</a>,
+in this example):
+</p>
+
+<pre>
+$ cd tools
+$ go test ./...
+</pre>
+
+<p>
+If you're concerned about the build status,
+you can check the <a href="https://build.golang.org">Build Dashboard</a>.
+Test failures may also be caught by the TryBots in code review.
+</p>
+
+<p>
+Some repositories, like
+<a href="https://go.googlesource.com/vscode-go">golang.org/x/vscode-go</a> will
+have different testing infrastructures, so always check the documentation
+for the repository in which you are working. The README file in the root of the
+repository will usually have this information.
+</p>
+
 <h3 id="mail">Step 4: Send changes for review</h3>
 
 <p>
@@ -720,10 +813,10 @@ when the change is applied.
 </p>
 
 <p>
-If you are sending a change against a subrepository, you must use
+If you are sending a change against a golang.org/x/... repository, you must use
 the fully-qualified syntax supported by GitHub to make sure the change is
-linked to the issue in the main repository, not the subrepository.
-All issues are tracked in the main repository's issue tracker.
+linked to the issue in the main repository, not the x/ repository.
+Most issues are tracked in the main repository's issue tracker.
 The correct form is "Fixes golang/go#159".
 </p>
 
@@ -1070,25 +1163,6 @@ $ $GODIR/bin/go run run.go
 </pre>
 </ul>
 
-<h3 id="subrepos">Contributing to subrepositories (golang.org/x/...)</h3>
-
-<p>
-If you are contributing a change to a subrepository, obtain the
-Go package using <code>go get</code>.
-For example, to contribute
-to <code>golang.org/x/oauth2</code>, check out the code by running:
-</p>
-
-<pre>
-$ go get -d golang.org/x/oauth2/...
-</pre>
-
-<p>
-Then, change your directory to the package's source directory
-(<code>$GOPATH/src/golang.org/x/oauth2</code>), and follow the
-normal contribution flow.
-</p>
-
 
 <h3 id="cc">Specifying a reviewer / CCing others</h3>
 
@@ -1209,5 +1283,5 @@ $ git codereview mail HEAD
 
 <p>
 Make sure to explicitly specify <code>HEAD</code>, which is usually not required when sending
-single changes.
+single changes. More details can be found in the <a href="https://pkg.go.dev/golang.org/x/review/git-codereview?tab=doc#hdr-Multiple_Commit_Work_Branches">git-codereview documentation</a>.
 </p>
diff --git a/doc/editors.html b/doc/editors.html
index 4ff35a58fc..22927bfa20 100644
--- a/doc/editors.html
+++ b/doc/editors.html
@@ -20,7 +20,7 @@ editing, navigation, testing, and debugging experience.
 
 <ul>
 <li><a href="https://github.com/fatih/vim-go">vim</a>: vim-go plugin provides Go programming language support</li>
-<li><a href="https://marketplace.visualstudio.com/items?itemName=lukehoban.Go">Visual Studio Code</a>:
+<li><a href="https://marketplace.visualstudio.com/items?itemName=ms-vscode.Go">Visual Studio Code</a>:
 Go extension provides support for the Go programming language</li>
 <li><a href="https://www.jetbrains.com/go">GoLand</a>: GoLand is distributed either as a standalone IDE
 or as a plugin for IntelliJ IDEA Ultimate</li>