third_party/pigweed/repo/CONTRIBUTING.md

   1 # Contributing
   2
   3 We'd love to accept your patches and contributions to Pigweed. There are just a
   4 few small guidelines you need to follow. Before making or sending major changes,
   5 please reach out on the [mailing list](mailto:pigweed@googlegroups.com) first to
   6 ensure the changes make sense for upstream. We generally go through a design
   7 phase before making large changes.
   8
   9 Before participating in our community, please take a moment to review our [code
  10 of conduct](CODE_OF_CONDUCT.md). We expect everyone who interacts with the
  11 project to respect these guidelines.
  12
  13 Pigweed contribution overview:
  14  1. One-time contributor setup:
  15    * Sign the [Contributor License Agreement](https://cla.developers.google.com/).
  16    * Verify that Git user email (git config user.email) is either Google Account
  17      email or an Alternate email for the Google account used to sign the CLA (Manage
  18      Google account->Personal Info->email).
  19    * Install the [Gerrit commit hook](CONTRIBUTING.md#gerrit-commit-hook) to
  20      automatically add a `Change-Id: ...` line to your commit.
  21    * Install the Pigweed presubmit check hook (`pw presubmit --install`).
  22      (recommended).
  23  1. Ensure all files include a correct [copyright and license header](CONTRIBUTING.md#source-code-headers).
  24  1. Run `pw presubmit` (see below) to detect style or compilation issues before
  25     uploading.
  26  1. Upload the change with `git push origin HEAD:refs/for/master`.
  27  1. Address any reviewer feedback by amending the commit (`git commit --amend`).
  28  1. Submit change to CI builders to merge. If you are not part of Pigweed's
  29     core team, you can ask the reviewer to add the `+2 CQ` vote, which will
  30     trigger a rebase asd submit once the builders pass.
  31
  32 ## Contributor License Agreement
  33
  34 Contributions to this project must be accompanied by a Contributor License
  35 Agreement. You (or your employer) retain the copyright to your contribution;
  36 this simply gives us permission to use and redistribute your contributions as
  37 part of the project. Head over to <https://cla.developers.google.com/> to see
  38 your current agreements on file or to sign a new one.
  39
  40 You generally only need to submit a CLA once, so if you've already submitted one
  41 (even if it was for a different project), you probably don't need to do it
  42 again.
  43
  44 ## Gerrit Commit Hook
  45
  46 Gerrit requires all changes to have a `Change-Id` tag at the bottom of each CL.
  47 You should set this up to be done automatically using the instructions below.
  48
  49 **Linux/macOS**<br/>
  50 ```bash
  51 $ f=`git rev-parse --git-dir`/hooks/commit-msg ; mkdir -p $(dirname $f) ; curl -Lo $f https://gerrit-review.googlesource.com/tools/hooks/commit-msg ; chmod +x $f
  52 ```
  53
  54 **Windows**<br/>
  55 Download [the Gerrit commit hook](https://gerrit-review.googlesource.com/tools/hooks/commit-msg)
  56 and then copy it to the `.git\hooks` directory in the Pigweed repository.
  57 ```batch
  58 copy %HOMEPATH%\Downloads\commit-msg %HOMEPATH%\pigweed\.git\hooks\commit-msg
  59 ```
  60
  61 ## Code Reviews
  62
  63 All Pigweed development happens on Gerrit, following the [typical Gerrit
  64 development workflow](http://ceres-solver.org/contributing.html). Consult
  65 [Gerrit User Guide](https://gerrit-documentation.storage.googleapis.com/Documentation/2.12.3/intro-user.html)
  66 for more information on using Gerrit.
  67
  68 In the future we may support GitHub pull requests, but until that time we will
  69 close GitHub pull requests and ask that the changes be uploaded to Gerrit
  70 instead.
  71
  72 ## Community Guidelines
  73
  74 This project follows [Google's Open Source Community
  75 Guidelines](https://opensource.google/conduct/) and the [Pigweed Code of
  76 Conduct](CODE_OF_CONDUCT.md).
  77
  78 ## Source Code Headers
  79
  80 Every Pigweed file containing source code must include copyright and license
  81 information. This includes any JS/CSS files that you might be serving out to
  82 browsers.
  83
  84 Apache header for C and C++ files:
  85
  86 ```javascript
  87 // Copyright 2020 The Pigweed Authors
  88 //
  89 // Licensed under the Apache License, Version 2.0 (the "License"); you may not
  90 // use this file except in compliance with the License. You may obtain a copy of
  91 // the License at
  92 //
  93 //     https://www.apache.org/licenses/LICENSE-2.0
  94 //
  95 // Unless required by applicable law or agreed to in writing, software
  96 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  97 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  98 // License for the specific language governing permissions and limitations under
  99 // the License.
 100 ```
 101
 102 Apache header for Python and GN files:
 103
 104 ```python
 105 # Copyright 2020 The Pigweed Authors
 106 #
 107 # Licensed under the Apache License, Version 2.0 (the "License"); you may not
 108 # use this file except in compliance with the License. You may obtain a copy of
 109 # the License at
 110 #
 111 #     https://www.apache.org/licenses/LICENSE-2.0
 112 #
 113 # Unless required by applicable law or agreed to in writing, software
 114 # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 115 # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 116 # License for the specific language governing permissions and limitations under
 117 # the License.
 118 ```
 119
 120 ## Continuous Integration
 121
 122 All Pigweed CLs must adhere to Pigweed's style guide and pass a suite of
 123 automated builds, tests, and style checks to be merged upstream. Much of this
 124 checking is done using Pigweed's pw_presubmit module by automated builders. To
 125 speed up the review process, consider adding `pw presubmit` as a git push hook
 126 using the following command:
 127
 128 **Linux/macOS**<br/>
 129 ```bash
 130 $ pw presubmit --install
 131 ```
 132
 133 This will be effectively the same as running the following command before every
 134 `git push`:
 135 ```bash
 136 $ pw presubmit --program quick
 137 ```
 138
 139 ![pigweed presubmit demonstration](pw_presubmit/docs/pw_presubmit_demo.gif)
 140
 141 Running `pw presubmit` manually will default to running the `full` presubmit
 142 program.
 143
 144 If you ever need to bypass the presubmit hook (due to it being broken, for example) you
 145 may push using this command:
 146
 147 ```bash
 148 $ git push origin HEAD:refs/for/master --no-verify
 149 ```