I want to share some particular insights I gained after attending the Contribution Workshop at GopherCon 2018.
The purpose of this post is to allow you to be able to contribute to Golang as easily as possible and to provide you with some helpful tips. These tips are coalesced from multiple sources and my own troubleshooting.
We are going to cover Gerrit…but don’t be disheartened. Interacting with Gerrit has evolved into an effortless process using the available tooling.
So first let’s get the obvious prerequisites out of the way.
You will need to have
You will need to have signed either an individual or corporate license agreement. Remember to use the google account you intend to contribute with. These are the links you need to care about:
You will need to have git installed and configured with the email address you intend to use for making contributions. You will also need to configure git authentication with Google’s Gerrit servers.
Go to https://go-review.googlesource.com/login/ and sign in using the same
google account. Gerrit email needs to match the email used in your
CLis an abbreviation for “changelist” which is the same as “change”.
-2: this shall not be merged -1: I would prefer this is not merged as is 0: no score, can be applied to a regular ol’ comment +1: looks good to me, but someone else must approve +2: looks good to me, approved (“Go Approvers” only)
Every change needs +2 before it gets merged.
go-contrib-init is handy-dandy tool created to make our lives easier when contributing to
go get -u golang.org/x/tools/cmd/go-contrib-init
Ensure that the binary is available on the
This tool will:
git clone https://go.googlesource.com/go $HOME/workspace/golang cd $HOME/workspace/golang go-contrib-init # All good. Happy hacking!
This might require a little more understanding. If you’d like to contribute to
a subrepository of golang like
tools you must…
go get golang.org/x/tools cd $GOPATH/src/golang.org/x/tools go-contrib-init -repo tools # All good. Happy hacking! # Remember to squash your revised commits and preserve the magic Change-Id lines. # Next steps: https://golang.org/doc/contribute.html#commit_changes # Interesting point here, the remote will already be the Gerrit server git remote -v # origin https://go.googlesource.com/tools (fetch)
The important points to take note of are:
golang.org/x/tools --> go.googlesource.com/tools --> github.com/golang/tools
go-contrib-initwill check the paths of the source code and the remote origin.
A good way to contribute is by looking for a function that requires an example or even better, a simple typo!
However, check https://tip.golang.org before looking for any changes because the example you may want to write may already have been written. This contains the latest merged CLs and has the most up to date version of the docs.
Say I want to add an example to a function specified in the
cd $HOME/workspace/golang/src/fmt vim example_test.go
By convention all the examples are written in
Check out the link below to see how to write an example, or just look at the examples already there and mess around.
Once you’ve written your example, you want to make sure that it runs and looks good.
If your example has some
// Output defined, you want to make sure the output
go test example_test.go
GOROOT=$HOME/workspace/golang godoc -http=:6060
Open your browser to http://localhost:6060 and navigate to the page that you want to review.
Yes, run all the tests…just to be sure
cd $HOME/workspace/golang/src ./all.bash
Now this is the part you all have been waiting for…
Once you are satisfied, create a branch and add your changes.
git checkout -b mybranch git add
Commit the change using the following guidelines for commit messages.
This is important!! You will be asked to update the
CL commit message if the message isn’t formatted correctly. And ideally, you’d
be referencing a pre-existing Github issue with the
git change # or git codereview change
Submit the patch
git mail # or git codereview mail
If you’d like to make further changes just redo the steps above.
git add . git change git mail
The Googlers said the convention is to submit a change with a single commit. Gerrit will display the patches made.
Go to your dashboard and keep up with the CLs.
And that’s pretty much it. There’s a lot more reading on the topic but as mentioned in the beginning, this post was intended for the fastest way to get you setup and started.
Take a another look at these resources: