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 `go-contrib-init` is handy-dandy tool created to make our lives easier when contributing to Golang.
go get -u golang.org/x/tools/cmd/go-contrib-init
Ensure that the binary is available on the `$PATH`. This tool will: - Check your CLA is valid - Check the repo’s remote origin to make sure that it is pointing to a Gerrit server like go.googlesource.com - Install `git-codereview` tool - Setup git aliases for git-codereview # Step 1: Getting the source code ## Core
git clone https://go.googlesource.com/go $HOME/workspace/golang cd $HOME/workspace/golang go-contrib-init
## Subrepositories This might require a little more understanding. If you'd like to contribute to a [subrepository of golang](https://godoc.org/-/subrepo) like `crypto` or `tools` you must... ```bash 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-init` will check the paths of the source code and the remote origin. __More Info:__ - [How to Contribute to Go](https://docs.google.com/presentation/d/14TfQtrsnz1yvOrX3uRa7ebkbOI3aByUB6dvvFIMXQ-8/edit?usp=sharing) presentation. - [Contribution Guide](https://golang.org/doc/contribute.html) ## Step 2: Contributing... ### Let's write an example 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 `fmt` package.
cd $HOME/workspace/golang/src/fmt vim example_test.go
By convention all the examples are written in `example_test.go` files. Check out the link below to see how to write an example, or just look at the examples already there and mess around. __More Info:__ - [How to write an example]( https://golang.org/pkg/testing/#hdr-Examples) ## Step 3: Testing the Example Once you've written your example, you want to make sure that it runs and looks good. #### 1. Run the example test If your example has some `// Output` defined, you want to make sure the output is correct.
go test example_test.go
#### 2. Check to see how it looks
GOROOT=$HOME/workspace/golang godoc -http=:6060
Open your browser to http://localhost:6060 and navigate to the page that you want to review. #### 3. Last but not least... Yes, run all the tests...just to be sure ```bash 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.
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: