Contributing to the Go project
This blog was originally written for Gopher Academy’s Advent 2016 series, but it is also mirrored here for convenience. Enjoy!
Please note that the Contribution Guide document has seen some major updates since this blog was originally posted. This blog is preserved here for historical purposes.
Contributing to the Go project can seem overwhelming, especially at first. The official Contribution Guidelines document is rather lengthy, but after working through the initial Google CLA and Gerrit authentication process, it becomes much easier to contribute to the project.
This post will attempt to demystify the process behind contributing to the Go project, in an effort to encourage all Gophers to try to tackle an issue or solve a bug upstream for the benefit of others.
Please note: this post attempts to simplify the steps laid out in the official Go Contribution Guidelines document, but it is entirely possible that it may contain incorrect information or become outdated over time. When in doubt, refer to the Contribution Guidelines or consult one of the many help forums available for Go.
Gerrit Registration and Google CLA
The Go project uses a system called Gerrit for code review. Gerrit is where CLs (change lists; akin to a GitHub pull request) are reviewed and submitted for inclusion in the upstream Go repositories.
To authenticate to Gerrit, a Google account must be used. Visit go.googlesource.com, click “Generate Password” on the top right menu, and follow the instructions. Take note of the Google account selected, as it must be used for all remaining steps.
Next, register with Gerrit using the same Google account previously selected.
Finally, you (or your organization) must agree to a Google Contributor License Agreement (CLA). If you are the copyright holder for your contributions, you must agree to the individual CLA.
If your organization is the copyright holder for your contributions, your organization must agree to the corporate CLA.
It is recommended to install the
git-codereview tool to simplify the
contribution process. This tool is not strictly necessary, but this guide
will assume that you are using it to submit your contributions.
go get -u golang.org/x/review/git-codereview
git-codereview is installed, it is recommended to set up aliases for
its commands in your Git configuration file (typically
This guide will also assume that these aliases are in place.
[alias] change = codereview change gofmt = codereview gofmt mail = codereview mail pending = codereview pending submit = codereview submit sync = codereview sync
Finding an issue to work on
With the previous steps completed, you are now ready to begin contributing to the Go project. To find an issue to work on, browse through the Go issue tracker. Specifically, searching for “open” issues with the “HelpWanted” label can be a great starting point.
Once you’ve found an issue you’d like to work on, leave a comment stating that you’d like to look into solving an issue. This helps prevent duplication of work due to lack of communication.
There are many different repositories that belong under the Go project umbrella, in addition to the main “go” repository. Visit go.googlesource.com to browse a list of all available repositories.
For purposes of demonstration, we will clone the “go” repository, containing
go tool, standard library, and runtime.
git clone https://go.googlesource.com/go
Making a contribution
Before making any changes, it is a good idea to sync your local repository with the upstream repository.
Begin working on your change. Remember to always use tools like
go vet on your code, and try to follow the conventions already in
place in code you are working on.
Once your change is complete (and tests have been written!), run tests for the entire tree to ensure your changes don’t break other packages or programs.
cd go/src ./all.bash
all.bash completes, it should print the output
ALL TESTS PASSED.
At this point, you are ready to submit your change for review.
Submitting your contribution
git commands like
git add and
git rm to stage your
changes. When ready to submit your changes, think of a meaningful branch
name and run:
git change <branch>
This will open a commit message file in your editor (using
There are some conventions that should be followed for commit messages, including:
- commit message should be prefixed with package name
- a one-line summary of the change
- if needed, a detailed description of the change (written in complete sentences with proper punctuation)
- the phrase “Fixes ###”, where ### is the Go issue you are resolving
An example of a commit message in this style, from the Contribution Guidelines:
math: improve Sin, Cos and Tan precision for very large arguments The existing implementation has poor numerical properties for large arguments, so use the McGillicutty algorithm to improve accuracy above 1e10. The algorithm is described at http://wikipedia.org/wiki/McGillicutty_Algorithm Fixes #159
If you wish to make further changes, use normal
git commands and
git change again to amend your commit. It is very common that
a given code review will often go through several rounds of feedback and
requested changes. Don’t be intimidated when asked to make changes
to your contribution!
Finally, submit your change to Gerrit by running:
The output of
git mail will print a link to where your change can be
found, such as:
remote: New Changes: remote: https://go-review.googlesource.com/99999 math: improved Sin, Cos and Tan precision for very large arguments
Gerrit code review
Now that your change has been submitted, it can be reviewed by a member of the Go team and others in the community. Code review comments may be addressed by amending your changes using the process above.
In addition, this is the stage where the “TryBots” are run, by assigning
Run-TryBot +1. This starts an automated testing process which
builds your change against the entire Go tree using a multitude of
different operating systems and CPU architectures.
At this point, any number of actions can take place with your change.
Typically, a member of the Go team will comment with a
label, which can be interpreted as follows:
-2: I am strongly against this change and will almost certainly not be persuaded otherwise
-1: I disagree with this change, but could be persuaded otherwise
+1: this change looks good to me, but someone else must approve
+2: this change looks good to me, and is ready for submission once the TryBots indicate a change is OK
Depending on the
Code-Review label applied and the ensuing discussion,
your change may or may not be accepted into the project.
In particular, if you submit a change with no issue filed and no discussion beforehand, you can be almost certain it will be rejected.
In summary, contributing to the Go project can be intimidating, but is an excellent way to give back to the Go community and to gain experience working on a large open source project, used by thousands of people all over the world.
If your first change is rejected, be polite and ask for clarification on why, if needed. If you disagree with a comment, state your case concisely and make sure that no misunderstandings take place.
If you have any questions or would like to hear about my own experiences contributing to the Go project, feel free to contact me: “mdlayher” on Gophers Slack!