Keir Mierle | 72cae43 | 2021-04-10 02:03:40 -0700 | [diff] [blame] | 1 | .. _docs-contributing: |
| 2 | |
| 3 | ============ |
| 4 | Contributing |
| 5 | ============ |
| 6 | We'd love to accept your patches and contributions to Pigweed. There are just a |
| 7 | few small guidelines you need to follow. Before making or sending major |
| 8 | changes, please reach out on the `mailing list |
| 9 | <https://groups.google.com/forum/#!forum/pigweed>`_ first to ensure the changes |
| 10 | make sense for upstream. We generally go through a design phase before making |
| 11 | large changes. |
| 12 | |
| 13 | Before participating in our community, please take a moment to review our |
| 14 | :ref:`docs-code-of-conduct`. We expect everyone who interacts with the project |
| 15 | to respect these guidelines. |
| 16 | |
| 17 | Pigweed contribution overview |
| 18 | ----------------------------- |
| 19 | |
| 20 | #. One-time contributor setup: |
| 21 | |
| 22 | - Sign the `Contributor License Agreement <https://cla.developers.google.com/>`_. |
| 23 | - Verify that your Git user email (git config user.email) is either Google |
| 24 | Account email or an Alternate email for the Google account used to sign |
| 25 | the CLA (Manage Google account → Personal Info → email) |
Adam MacBeth | 89ff5f9 | 2021-06-08 17:55:13 +0000 | [diff] [blame] | 26 | - Obtain a login cookie from Gerrit's `new-password <https://pigweed-review.googlesource.com/new-password>`_ page |
Keir Mierle | 72cae43 | 2021-04-10 02:03:40 -0700 | [diff] [blame] | 27 | - Install the Gerrit commit hook to automatically add a ``Change-Id: ...`` |
| 28 | line to your commit |
| 29 | - Install the Pigweed presubmit check hook with ``pw presubmit --install`` |
| 30 | |
| 31 | #. Ensure all files include the correct copyright and license headers |
| 32 | #. Include any necessary changes to the documentation |
| 33 | #. Run :ref:`module-pw_presubmit` to detect style or compilation issues before |
| 34 | uploading |
Rob Mohr | dfbdd1f | 2021-06-11 08:21:17 -0700 | [diff] [blame^] | 35 | #. Upload the change with ``git push origin HEAD:refs/for/main`` |
Keir Mierle | 72cae43 | 2021-04-10 02:03:40 -0700 | [diff] [blame] | 36 | #. Address any reviewer feedback by amending the commit (``git commit --amend``) |
| 37 | #. Submit change to CI builders to merge. If you are not part of Pigweed's |
| 38 | core team, you can ask the reviewer to add the `+2 CQ` vote, which will |
| 39 | trigger a rebase and submit once the builders pass |
| 40 | |
| 41 | .. note:: |
| 42 | |
| 43 | If you have any trouble with this flow, reach out in our `chat room |
| 44 | <https://discord.gg/M9NSeTA>`_ or on the `mailing list |
| 45 | <https://groups.google.com/forum/#!forum/pigweed>`_ for help. |
| 46 | |
| 47 | Contributor License Agreement |
| 48 | ----------------------------- |
| 49 | Contributions to this project must be accompanied by a Contributor License |
| 50 | Agreement. You (or your employer) retain the copyright to your contribution; |
| 51 | this simply gives us permission to use and redistribute your contributions as |
| 52 | part of the project. Head over to <https://cla.developers.google.com/> to see |
| 53 | your current agreements on file or to sign a new one. |
| 54 | |
| 55 | You generally only need to submit a CLA once, so if you've already submitted one |
| 56 | (even if it was for a different project), you probably don't need to do it |
| 57 | again. |
| 58 | |
| 59 | Gerrit Commit Hook |
| 60 | ------------------ |
| 61 | Gerrit requires all changes to have a ``Change-Id`` tag at the bottom of each |
| 62 | commit message. You should set this up to be done automatically using the |
| 63 | instructions below. |
| 64 | |
| 65 | **Linux/macOS** |
| 66 | |
| 67 | .. code:: bash |
| 68 | |
| 69 | $ 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 |
| 70 | |
| 71 | **Windows** |
| 72 | |
| 73 | Download `the Gerrit commit hook |
| 74 | <https://gerrit-review.googlesource.com/tools/hooks/commit-msg>`_ and then copy |
| 75 | it to the ``.git\hooks`` directory in the Pigweed repository. |
| 76 | |
| 77 | .. code:: |
| 78 | |
| 79 | copy %HOMEPATH%\Downloads\commit-msg %HOMEPATH%\pigweed\.git\hooks\commit-msg |
| 80 | |
| 81 | Documentation |
| 82 | ------------- |
| 83 | |
| 84 | All Pigweed changes must either |
| 85 | |
| 86 | #. Include updates to documentation, or |
| 87 | #. Include ``No-Docs-Update-Reason: <reason>`` in the commit message or a |
| 88 | Gerrit comment on the CL. For example: |
| 89 | |
| 90 | * ``No-Docs-Update-Reason: formatting tweaks`` |
| 91 | * ``No-Docs-Update-Reason: internal cleanups`` |
| 92 | * ``No-Docs-Update-Reason: bugfix`` |
| 93 | |
| 94 | It's acceptable to only document new changes in an otherwise underdocumented |
| 95 | module, but it's not acceptable to not document new changes because the module |
| 96 | doesn't have any other documentation. |
| 97 | |
| 98 | Code Reviews |
| 99 | ------------ |
| 100 | All Pigweed development happens on Gerrit, following the `typical Gerrit |
| 101 | development workflow <http://ceres-solver.org/contributing.html>`_. Consult the |
| 102 | `Gerrit User Guide |
| 103 | <https://gerrit-documentation.storage.googleapis.com/Documentation/2.12.3/intro-user.html>`_ |
| 104 | for more information on using Gerrit. |
| 105 | |
| 106 | In the future we may support GitHub pull requests, but until that time we will |
| 107 | close GitHub pull requests and ask that the changes be uploaded to Gerrit |
| 108 | instead. |
| 109 | |
| 110 | Community Guidelines |
| 111 | -------------------- |
| 112 | This project follows `Google's Open Source Community Guidelines |
| 113 | <https://opensource.google/conduct/>`_ and the :ref:`docs-code-of-conduct`. |
| 114 | |
| 115 | Source Code Headers |
| 116 | ------------------- |
| 117 | Every Pigweed file containing source code must include copyright and license |
| 118 | information. This includes any JS/CSS files that you might be serving out to |
| 119 | browsers. |
| 120 | |
| 121 | Apache header for C and C++ files: |
| 122 | |
| 123 | .. code:: none |
| 124 | |
| 125 | // Copyright 2021 The Pigweed Authors |
| 126 | // |
| 127 | // Licensed under the Apache License, Version 2.0 (the "License"); you may not |
| 128 | // use this file except in compliance with the License. You may obtain a copy of |
| 129 | // the License at |
| 130 | // |
| 131 | // https://www.apache.org/licenses/LICENSE-2.0 |
| 132 | // |
| 133 | // Unless required by applicable law or agreed to in writing, software |
| 134 | // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
| 135 | // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the |
| 136 | // License for the specific language governing permissions and limitations under |
| 137 | // the License. |
| 138 | |
| 139 | Apache header for Python and GN files: |
| 140 | |
| 141 | .. code:: none |
| 142 | |
| 143 | # Copyright 2020 The Pigweed Authors |
| 144 | # |
| 145 | # Licensed under the Apache License, Version 2.0 (the "License"); you may not |
| 146 | # use this file except in compliance with the License. You may obtain a copy of |
| 147 | # the License at |
| 148 | # |
| 149 | # https://www.apache.org/licenses/LICENSE-2.0 |
| 150 | # |
| 151 | # Unless required by applicable law or agreed to in writing, software |
| 152 | # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
| 153 | # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the |
| 154 | # License for the specific language governing permissions and limitations under |
| 155 | # the License. |
| 156 | |
| 157 | Presubmit Checks and Continuous Integration |
| 158 | ------------------------------------------- |
| 159 | All Pigweed change lists (CLs) must adhere to Pigweed's style guide and pass a |
| 160 | suite of automated builds, tests, and style checks to be merged upstream. Much |
| 161 | of this checking is done using Pigweed's ``pw_presubmit`` module by automated |
| 162 | builders. These builders run before each Pigweed CL is submitted and in our |
| 163 | continuous integration infrastructure (see `Pigweed's build console |
| 164 | <https://ci.chromium.org/p/pigweed/g/pigweed/console>`_). |
| 165 | |
| 166 | Running Presubmit Checks |
| 167 | ------------------------ |
| 168 | To run automated presubmit checks on a pending CL, click the ``CQ DRY RUN`` |
| 169 | button in the Gerrit UI. The results appear in the Tryjobs section, below the |
| 170 | source listing. Jobs that passed are green; jobs that failed are red. |
| 171 | |
| 172 | If all checks pass, you will see a ``Dry run: This CL passed the CQ dry run.`` |
| 173 | comment on your change. If any checks fail, you will see a ``Dry run: Failed |
| 174 | builds:`` message. All failures must be addressed before submitting. |
| 175 | |
| 176 | In addition to the publicly visible presubmit checks, Pigweed runs internal |
| 177 | presubmit checks that are only visible within Google. If any these checks fail, |
| 178 | external developers will see a ``Dry run: Failed builds:`` comment on the CL, |
| 179 | even if all visible checks passed. Reach out to the Pigweed team for help |
| 180 | addressing these issues. |
| 181 | |
| 182 | Project Presubmit Checks |
| 183 | ------------------------ |
| 184 | In addition to Pigweed's presubmit checks, some projects that use Pigweed run |
| 185 | their presubmit checks in Pigweed's infrastructure. This supports a development |
| 186 | flow where projects automatically update their Pigweed submodule if their tests |
| 187 | pass. If a project cannot build against Pigweed's tip-of-tree, it will stay on |
| 188 | a fixed Pigweed revision until the issues are fixed. See the `sample project |
| 189 | <https://pigweed.googlesource.com/pigweed/sample_project/>`_ for an example of |
| 190 | this. |
| 191 | |
| 192 | Pigweed does its best to keep builds passing for dependent projects. In some |
| 193 | circumstances, the Pigweed maintainers may choose to merge changes that break |
| 194 | dependent projects. This will only be done if |
| 195 | |
| 196 | * a feature or fix is needed urgently in Pigweed or for a different project, |
| 197 | and |
| 198 | * the project broken by the change does not imminently need Pigweed updates. |
| 199 | |
| 200 | The downstream project will continue to build against their last working |
| 201 | revision of Pigweed until the incompatibilities are fixed. |
| 202 | |
| 203 | In these situations, Pigweed's commit queue submission process will fail for all |
| 204 | changes. If a change passes all presubmit checks except for known failures, the |
| 205 | Pigweed team may permit manual submission of the CL. Contact the Pigweed team |
| 206 | for submission approval. |
| 207 | |
| 208 | Running local presubmits |
| 209 | ------------------------ |
| 210 | To speed up the review process, consider adding :ref:`module-pw_presubmit` as a |
| 211 | git push hook using the following command: |
| 212 | |
| 213 | **Linux/macOS** |
| 214 | |
| 215 | .. code:: bash |
| 216 | |
| 217 | $ pw presubmit --install |
| 218 | |
| 219 | This will be effectively the same as running the following command before every |
| 220 | ``git push``: |
| 221 | |
| 222 | .. code:: bash |
| 223 | |
| 224 | $ pw presubmit |
| 225 | |
| 226 | |
| 227 | .. image:: ../pw_presubmit/docs/pw_presubmit_demo.gif |
| 228 | :width: 800 |
| 229 | :alt: pw presubmit demo |
| 230 | |
| 231 | If you ever need to bypass the presubmit hook (due to it being broken, for |
| 232 | example) you may push using this command: |
| 233 | |
| 234 | .. code:: bash |
| 235 | |
Rob Mohr | dfbdd1f | 2021-06-11 08:21:17 -0700 | [diff] [blame^] | 236 | $ git push origin HEAD:refs/for/main --no-verify |