From 325540922a228dd8ab80abb200b834d043d5b925 Mon Sep 17 00:00:00 2001 From: Rebecca Stambler Date: Thu, 21 May 2020 23:58:39 -0400 Subject: [PATCH] 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 TryBot-Result: Gobot Gobot Reviewed-by: Dmitri Shuralyov Reviewed-by: Hyang-Ah Hana Kim --- doc/contribute.html | 140 +++++++++++++++++++++++++++++++++----------- doc/editors.html | 2 +- 2 files changed, 108 insertions(+), 34 deletions(-) diff --git a/doc/contribute.html b/doc/contribute.html index 5fefac6bba6..6188ee197b1 100644 --- a/doc/contribute.html +++ b/doc/contribute.html @@ -263,6 +263,24 @@ a new issue or by claiming an existing one.

+

Where to contribute

+ +

+The Go project consists of the main +go 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, golang.org/x/pkgsite +is for pkg.go.dev, +golang.org/x/playground +is for the Go playground, and +golang.org/x/tools contains +a variety of Go tools, including the Go language server, +gopls. You can see a +list of all the golang.org/x/... repositories on +go.googlesource.com. +

+

Check the issue tracker

@@ -272,6 +290,13 @@ always the first place to go. Issues are triaged to categorize them and manage the workflow.

+

+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. +

+

Most issues will be marked with one of the following workflow labels:

@@ -329,11 +354,16 @@ the code review tool is not the place for high-level discussions.

When planning work, please note that the Go project follows a six-month development cycle. -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 +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 +the standard library +and the go command.

@@ -408,13 +438,29 @@ This is an overview of the overall process:

  • -Step 1: Clone the Go source code from go.googlesource.com -and make sure it's stable by compiling and testing it once: +Step 1: Clone the source code from go.googlesource.com and +make sure it's stable by compiling and testing it once. + +

    If you're making a change to the +main Go repository:

    + 
     $ git clone https://go.googlesource.com/go
 $ cd go/src
 $ ./all.bash                                # compile and test
    + +

    +If you're making a change to one of the golang.org/x/... repositories +(golang.org/x/tools, +in this example): +

    + +
    +$ git clone https://go.googlesource.com/tools
+$ cd tools
+$ go test ./...                             # compile and test
+
  • @@ -434,10 +480,18 @@ $ [etc.]
  • -Step 3: Test your changes, re-running all.bash. +Step 3: Test your changes, either by running the tests in the package +you edited or by re-running all.bash. + +

    In the main Go repository:

     $ ./all.bash    # recompile and test
    + +

    In a golang.org/x/... repository:

    +
    +$ go test ./... # recompile and test
+
  • @@ -465,7 +519,7 @@ The rest of this section describes these steps in more detail.

    -

    Step 1: Clone the Go source code

    +

    Step 1: Clone the source code

    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 GOPATH. Clone from go.googlesource.com (not GitHub):

    +

    Main Go repository:

     $ git clone https://go.googlesource.com/go
 $ cd go
    +

    golang.org/x/... repository

    +(golang.org/x/tools in this example): +
    +$ git clone https://go.googlesource.com/tools
+$ cd tools
+
    +

    Step 2: Prepare changes in a new branch

    @@ -543,9 +605,13 @@ into a single one.

    You've written and tested your code, but before sending code out for review, run all the tests for the whole -tree to make sure the changes don't break other packages or programs: +tree to make sure the changes don't break other packages or programs.

    +

    In the main Go repository

    + +

    This can be done by running all.bash:

    + 
     $ cd go/src
 $ ./all.bash
@@ -574,6 +640,33 @@ See also
 the section on how to test your changes quickly.
 
    
 
+
    In the golang.org/x/... repositories
    
+
+
    
+Run the tests for the entire repository
+(golang.org/x/tools,
+in this example):
+
    
+
+
    +$ cd tools
+$ go test ./...
+
    
+
+
    
+If you're concerned about the build status,
+you can check the Build Dashboard.
+Test failures may also be caught by the TryBots in code review.
+
    
+
+
    
+Some repositories, like
+golang.org/x/vscode-go 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.
+
    
+
 
    Step 4: Send changes for review
    
 
 
    
@@ -720,10 +813,10 @@ when the change is applied.
 
    
 
 
    
-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".
 
    
 
@@ -1070,25 +1163,6 @@ $ $GODIR/bin/go run run.go
-

Contributing to subrepositories (golang.org/x/...)

- -

-If you are contributing a change to a subrepository, obtain the -Go package using go get. -For example, to contribute -to golang.org/x/oauth2, check out the code by running: -

- -
-$ go get -d golang.org/x/oauth2/...
-
- -

-Then, change your directory to the package's source directory -($GOPATH/src/golang.org/x/oauth2), and follow the -normal contribution flow. -

-

Specifying a reviewer / CCing others

@@ -1209,5 +1283,5 @@ $ git codereview mail HEAD

Make sure to explicitly specify HEAD, which is usually not required when sending -single changes. +single changes. More details can be found in the git-codereview documentation.

diff --git a/doc/editors.html b/doc/editors.html index 4ff35a58fc1..22927bfa206 100644 --- a/doc/editors.html +++ b/doc/editors.html @@ -20,7 +20,7 @@ editing, navigation, testing, and debugging experience.
  • vim: vim-go plugin provides Go programming language support
    • -
  • Visual Studio Code: +
  • Visual Studio Code: Go extension provides support for the Go programming language
  • GoLand: GoLand is distributed either as a standalone IDE or as a plugin for IntelliJ IDEA Ultimate