Take another pass at CONTRIBUTING.md It's not obvious that the two workflows described behave very different w.r.t. what turns into a CL. Expand on this a bit. While I'm here, shift all the headers up so that the new subheads are a bit less deeply nested. Change-Id: I6296b5ba8c8c201dcae8b18542b25cf75aae1ee4 Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/83027 Commit-Queue: Lily Chen <chlily@google.com> Reviewed-by: Lily Chen <chlily@google.com> Auto-Submit: David Benjamin <davidben@google.com>
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7f08cc3..636d0e9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md
@@ -1,6 +1,6 @@ Want to contribute? Great! First, read this page (including the small print at the end). -### Before you contribute +# Before you contribute Before we can use your code, you must sign the [Google Individual Contributor License Agreement](https://cla.developers.google.com/about/google-individual) (CLA), which you can do online. The CLA is necessary mainly because you own the @@ -14,11 +14,11 @@ us first via email with your idea so that we can help out and possibly guide you. Coordinating up front makes it much easier to avoid frustration later on. -### Code reviews +# Code reviews All submissions, including submissions by project members, require review. We use [Gerrit](https://boringssl-review.googlesource.com) for this purpose. -#### Setup +## Setup If you have not done so on this machine, you will need to set up a password for Gerrit. Sign in with a Google account, visit [this link](https://boringssl.googlesource.com/), and click the "Generate @@ -28,14 +28,24 @@ your Google account. To do this visit the [Gerrit review server](https://boringssl-review.googlesource.com) and click "Sign in" (top right). -Finally, you will need to prepare your checkout to +## Uploading changes + +There are a few different workflows for uploading to Gerrit, depending on what +tools you have available and whether you are more familiar with Gerrit or +Chromium's `depot_tools`. + +**WARNING**: The two workflows, by default, convert branches and commits into +code review changes very differently. + +### Uploading directly to Gerrit + +To use the Gerrit workflow, you will need to prepare your checkout to [add Change-Ids](https://gerrit-review.googlesource.com/Documentation/cmd-hook-commit-msg.html) on commit. Run: curl -Lo .git/hooks/commit-msg https://boringssl-review.googlesource.com/tools/hooks/commit-msg chmod u+x .git/hooks/commit-msg -#### Uploading changes To upload a change, push it to the special `refs/for/main` target: git push origin HEAD:refs/for/main @@ -43,20 +53,39 @@ The output will then give you a link to the change. Add `agl@google.com`, `davidben@google.com` as reviewers. -Pushing a commit with the same Change-Id as an existing change will upload a new -version of it. (Use the `git rebase` or `git commit --amend` commands.) +Pushing a commit with the same `Change-Id` as an existing change will upload a new +version of it. (Gerrit refers to versions of a change as "patchsets".) The +`git rebase` or `git commit --amend` commands may be helpful to modify an +existing commit. Making changes as separate commits will result in multiple +Gerrit change, as described below. + +Pushing a series of commits will create a series of dependent changes. To upload +new versions of commits in the series, `git rebase -i` may be helpful. For more detailed instructions, see the [Gerrit User Guide](https://gerrit-review.googlesource.com/Documentation/intro-user.html). +Google employers may also find [go/gerrit-dev-workflows](https://goto.corp.google.com/gerrit-dev-workflows) +helpful. -As an alternative to pushing to `refs/for/main`: if you have Chromium's -`depot_tools` installed, you can simply run `git cl upload` to upload a change. -This also has the advantage of automatically running any relevant `PRESUBMIT.py` -checks. See [depot_tools +### Uploading using depot_tools + +If you have Chromium's `depot_tools` installed, you can use `git cl upload` to +upload a change. This also has the advantage of automatically running any +relevant `PRESUBMIT.py` checks, which can catch common/trivial errors locally at +upload time instead of waiting for a slower CQ run. + +By default, your entire branch will be squashed into a single Gerrit change. +This avoids the need for tools like `git commit --amend` to upload new versions +of the change. However, to upload a series of changes, you must create a series +of branches in your repository. Setting `gerrit.squash-uploads` to `false` in +`git config` disables this behavior and causes `git cl upload` to behave like +the Gerrit workflow above. + +See [depot_tools documentation](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools.html) for more info. -### Copyright headers +# Copyright headers New files contributed directly to BoringSSL should use the following copyright header, where `YEAR` is the year the file was added: @@ -89,7 +118,7 @@ // See the License for the specific language governing permissions and // limitations under the License. -### The small print +# The small print Contributions made by corporations are covered by a different agreement than the one above, the [Software Grant and Corporate Contributor License Agreement](https://cla.developers.google.com/about/google-corporate).