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