CONTRIBUTING.md: expand instructions
Change-Id: Ic50f1db5f36c0b3d81aba75f3b792151e35ccf31
Reviewed-on: https://code-review.googlesource.com/c/gocloud/+/44670
Reviewed-by: kokoro <noreply+kokoro@google.com>
Reviewed-by: Jean de Klerk <deklerk@google.com>
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index cc1c1d4..85ed4df 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,35 +1,98 @@
# Contributing
-1. Sign one of the contributor license agreements below.
-1. `go get golang.org/x/review/git-codereview` to install the code reviewing
-tool.
- 1. You will need to ensure that your `GOBIN` directory (by default
- `$GOPATH/bin`) is in your `PATH` so that git can find the command.
- 1. If you would like, you may want to set up aliases for git-codereview,
+1. [Install Go](https://golang.org/dl/).
+ 1. Ensure that your `GOBIN` directory (by default `$(go env GOPATH)/bin`)
+ is in your `PATH`.
+ 1. Check it's working by running `go version`.
+ * If it doesn't work, check the install location, usually
+ `/usr/local/go`, is on your `PATH`.
+
+1. Sign one of the
+[contributor license agreements](#contributor-license-agreements) below.
+
+1. Run `GO111MODULE=off go get golang.org/x/review/git-codereview` to install
+the code reviewing tool.
+
+ 1. Ensure it's working by running `git codereview` (check your `PATH` if
+ not).
+
+ 1. If you would like, you may want to set up aliases for `git-codereview`,
such that `git codereview change` becomes `git change`. See the
[godoc](https://godoc.org/golang.org/x/review/git-codereview) for details.
- 1. Should you run into issues with the git-codereview tool, please note
- that all error messages will assume that you have set up these aliases.
-1. Get the cloud package by running `go get -d cloud.google.com/go`.
- 1. If you have already checked out the source, make sure that the remote
- git origin is https://code.googlesource.com/gocloud:
+
+ * Should you run into issues with the `git-codereview` tool, please note
+ that all error messages will assume that you have set up these aliases.
+
+1. Change to a directory of your choosing and clone the repo.b
+
+ ```
+ cd ~/code
+ git clone https://code.googlesource.com/gocloud
+ ```
+
+ * If you have already checked out the source, make sure that the remote
+ `git` `origin` is https://code.googlesource.com/gocloud:
```
+ git remote -v
+ # ...
git remote set-url origin https://code.googlesource.com/gocloud
```
-1. Make sure your auth is configured correctly by visiting
-https://code.googlesource.com, clicking "Generate Password", and following the
-directions.
-1. Make changes and create a change by running `git codereview change <name>`,
-provide a commit message, and use `git codereview mail` to create a Gerrit CL.
-1. Keep amending to the change with `git codereview change` and mail as your
-receive feedback. Each new mailed amendment will create a new patch set for
-your change in Gerrit.
- - Note: if your change includes a breaking change, our breaking change
+ * The project uses [Go Modules](https://blog.golang.org/using-go-modules)
+ for dependency management See
+ [`gopls`](https://github.com/golang/go/wiki/gopls) for making your editor
+ work with modules.
+
+1. Change to the project directory:
+
+ ```
+ cd ~/code/gocloud
+ ```
+
+1. Make sure your `git` auth is configured correctly by visiting
+https://code.googlesource.com, clicking "Generate Password" at the top-right,
+and following the directions. Otherwise, `git codereview mail` in the next step
+will fail.
+
+1. Make changes then use `git codereview` to create a commit and create a Gerrit
+CL:
+
+ ```
+ git codereview change <name>
+ # Make changes.
+ git add ...
+ git codereview change
+ git codereview mail # If this fails, the error message will contain instructions to fix it.
+ ```
+
+ * This will create a new `git` branch for you to develop on. Once your
+ change is merged, you can delete this branch.
+
+1. As you make changes for code review, ammend the commit and re-mail the
+change:
+
+ ```
+ # Make more changes.
+ git add ...
+ git codereview change <name>
+ git codereview mail
+ ```
+
+ * **Warning**: do not change the `Change-Id` at the bottom of the commit
+ message - it's how Gerrit knows which change this is (or if it's new).
+
+ * When you fixes issues from code review, respond to each code review
+ message then click **Reply** at the top of the page.
+
+ * Each new mailed amendment will create a new patch set for
+ your change in Gerrit. Patch sets can be compared and reviewed.
+
+ * **Note**: if your change includes a breaking change, our breaking change
detector will cause CI/CD to fail. If your breaking change is acceptable
- in some way, add BREAKING_CHANGE_ACCEPTABLE=<reason> to cause the
- detector not to be run and to make it clear why that is acceptable.
+ in some way, add a `BREAKING_CHANGE_ACCEPTABLE=<reason>` line to the commit
+ message to cause the detector not to be run and to make it clear why that is
+ acceptable.
## Integration Tests
