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>
diff --git a/doc/contribute.html b/doc/contribute.html
index 5fefac6..6188ee1 100644
--- a/doc/contribute.html
+++ b/doc/contribute.html
@@ -263,6 +263,24 @@
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 @@
</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 @@
<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 @@
<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 @@
</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 @@
</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 @@
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 @@
<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 @@
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 @@
</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 @@
</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 @@
<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 4ff35a5..22927bf 100644
--- a/doc/editors.html
+++ b/doc/editors.html
@@ -20,7 +20,7 @@
<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>
