Contributing

We’d love to accept your patches and contributions to Pigweed. There are just a few small guidelines you need to follow. Before making or sending major changes, please reach out on the mailing list first to ensure the changes make sense for upstream. We generally go through a design phase before making large changes.

Before participating in our community, please take a moment to review our Code of Conduct. We expect everyone who interacts with the project to respect these guidelines.

Pigweed contribution overview

  1. One-time contributor setup:

  • Sign the Contributor License Agreement.

  • Verify that your Git user email (git config user.email) is either Google Account email or an Alternate email for the Google account used to sign the CLA (Manage Google account → Personal Info → email)

  • Sign in to Gerrit to create an account using the same Google account you used above.

  • Obtain a login cookie from Gerrit’s new-password page

  • Install the Gerrit commit hook to automatically add a Change-Id: ... line to your commit

  • Install the Pigweed presubmit check hook with pw presubmit --install

  1. Ensure all files include the correct copyright and license headers

  2. Include any necessary changes to the documentation

  3. Run pw_presubmit to detect style or compilation issues before uploading

  4. Upload the change with git push origin HEAD:refs/for/main

  5. Address any reviewer feedback by amending the commit (git commit --amend)

  6. Submit change to CI builders to merge. If you are not part of Pigweed’s core team, you can ask the reviewer to add the +2 CQ vote, which will trigger a rebase and submit once the builders pass

Note

If you have any trouble with this flow, reach out in our chat room or on the mailing list for help.

Contributor License Agreement

Contributions to this project must be accompanied by a Contributor License Agreement. You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project. Head over to <https://cla.developers.google.com/> to see your current agreements on file or to sign a new one.

You generally only need to submit a CLA once, so if you’ve already submitted one (even if it was for a different project), you probably don’t need to do it again.

Gerrit Commit Hook

Gerrit requires all changes to have a Change-Id tag at the bottom of each commit message. You should set this up to be done automatically using the instructions below.

Linux/macOS

$ 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

Windows

Download the Gerrit commit hook and then copy it to the .git\hooks directory in the Pigweed repository.

copy %HOMEPATH%\Downloads\commit-msg %HOMEPATH%\pigweed\.git\hooks\commit-msg

Commit message

Consider the following when writing a commit message:

  1. Documentation and comments are better - Consider whether the commit message contents would be better expressed in the documentation or code comments. Docs and code comments are durable and readable later; commit messages are rarely read after the change lands.

  2. Include why the change is made, not just what the change is - It is important to include a “why” component in most commits. Sometimes, why is evident - for example, reducing memory usage, or optimizing. But it is often not. Err on the side of over-explaining why, not under-explaining why.

Pigweed commit messages should conform to the following style:

Yes:

pw_some_module: Short capitalized description

Details about the change here. Include a summary of the what, and a clear
description of why the change is needed for future maintainers.

Consider what parts of the commit message are better suited for
documentation.

Yes: Small number of modules affected; use {} syntax.

pw_{foo, bar, baz}: Change something in a few places

When changes cross a few modules, include them with the syntax shown above.

Yes: targets are effectively modules, even though they’re nested, so they get a / character.

targets/xyz123: Tweak support for XYZ's PQR

Yes: Uses imperative style for subject and text.

pw_something: Add foo and bar functions

This commit correctly uses imperative present-tense style.

No: Uses non-imperative style for subject and text.

pw_something: Adds more things

Use present tense imperative style for subjects and commit. The above
subject has a plural "Adds" which is incorrect; should be "Add".

Yes: Use bulleted lists when multiple changes are in a single CL. Prefer smaller CLs, but larger CLs are a practical reality.

pw_complicated_module: Pre-work for refactor

Prepare for a bigger refactor by reworking some arguments before the larger
change. This change must land in downstream projects before the refactor to
enable a smooth transition to the new API.

- Add arguments to MyImportantClass::MyFunction
- Update MyImportantClass to handle precondition Y
- Add stub functions to be used during the transition

No: Run on paragraph instead of bulleted list

pw_foo: Many things in a giant BWOT

This CL does A, B, and C. The commit message is a Big Wall Of Text (BWOT),
which we try to discourage in Pigweed. Also changes X and Y, because Z and
Q. Furthermore, in some cases, adds a new Foo (with Bar, because we want
to). Also refactors qux and quz.

No: Doesn’t capitalize the subject

pw_foo: do a thing

Above subject is incorrect, since it is a sentence style subject.

Yes: Doesn’t capitalize the subject when subject’s first word is a lowercase identifier.

pw_foo: std::unique_lock cleanup

This commit message demonstrates the subject when the subject has an
identifier for the first word. In that case, follow the identifier casing
instead of capitalizing.

However, imperative style subjects often have the identifier elsewhere in
the subject; for example:

  pw_foo: Improve use of std::unique_lock

No: Uses a non-standard [] to indicate moduule:

[pw_foo]: Do a thing

No: Has a period at the end of the subject

pw_bar: Do somehthing great.

No: Puts extra stuff after the module which isn’t a module.

pw_bar/byte_builder: Add more stuff to builder

Documentation

All Pigweed changes must either

  1. Include updates to documentation, or

  2. Include No-Docs-Update-Reason: <reason> in a Gerrit comment on the CL. For example:

    • No-Docs-Update-Reason: formatting tweaks

    • No-Docs-Update-Reason: internal cleanups

    • No-Docs-Update-Reason: bugfix

It’s acceptable to only document new changes in an otherwise underdocumented module, but it’s not acceptable to not document new changes because the module doesn’t have any other documentation.

Code Reviews

All Pigweed development happens on Gerrit, following the typical Gerrit development workflow. Consult the Gerrit User Guide for more information on using Gerrit.

In the future we may support GitHub pull requests, but until that time we will close GitHub pull requests and ask that the changes be uploaded to Gerrit instead.

Community Guidelines

This project follows Google’s Open Source Community Guidelines and the Code of Conduct.

Source Code Headers

Every Pigweed file containing source code must include copyright and license information. This includes any JS/CSS files that you might be serving out to browsers.

Apache header for C and C++ files:

// Copyright 2021 The Pigweed Authors
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
// use this file except in compliance with the License. You may obtain a copy of
// the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
// License for the specific language governing permissions and limitations under
// the License.

Apache header for Python and GN files:

# Copyright 2020 The Pigweed Authors
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may not
# use this file except in compliance with the License. You may obtain a copy of
# the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations under
# the License.

Presubmit Checks and Continuous Integration

All Pigweed change lists (CLs) must adhere to Pigweed’s style guide and pass a suite of automated builds, tests, and style checks to be merged upstream. Much of this checking is done using Pigweed’s pw_presubmit module by automated builders. These builders run before each Pigweed CL is submitted and in our continuous integration infrastructure (see Pigweed’s build console).

Running Presubmit Checks

To run automated presubmit checks on a pending CL, click the CQ DRY RUN button in the Gerrit UI. The results appear in the Tryjobs section, below the source listing. Jobs that passed are green; jobs that failed are red.

If all checks pass, you will see a Dry run: This CL passed the CQ dry run. comment on your change. If any checks fail, you will see a Dry run: Failed builds: message. All failures must be addressed before submitting.

In addition to the publicly visible presubmit checks, Pigweed runs internal presubmit checks that are only visible within Google. If any these checks fail, external developers will see a Dry run: Failed builds: comment on the CL, even if all visible checks passed. Reach out to the Pigweed team for help addressing these issues.

Project Presubmit Checks

In addition to Pigweed’s presubmit checks, some projects that use Pigweed run their presubmit checks in Pigweed’s infrastructure. This supports a development flow where projects automatically update their Pigweed submodule if their tests pass. If a project cannot build against Pigweed’s tip-of-tree, it will stay on a fixed Pigweed revision until the issues are fixed. See the sample project for an example of this.

Pigweed does its best to keep builds passing for dependent projects. In some circumstances, the Pigweed maintainers may choose to merge changes that break dependent projects. This will only be done if

  • a feature or fix is needed urgently in Pigweed or for a different project, and

  • the project broken by the change does not imminently need Pigweed updates.

The downstream project will continue to build against their last working revision of Pigweed until the incompatibilities are fixed.

In these situations, Pigweed’s commit queue submission process will fail for all changes. If a change passes all presubmit checks except for known failures, the Pigweed team may permit manual submission of the CL. Contact the Pigweed team for submission approval.

Running local presubmits

To speed up the review process, consider adding pw_presubmit as a git push hook using the following command:

Linux/macOS

$ pw presubmit --install

This will be effectively the same as running the following command before every git push:

$ pw presubmit
pw presubmit demo

If you ever need to bypass the presubmit hook (due to it being broken, for example) you may push using this command:

$ git push origin HEAD:refs/for/main --no-verify