Contributing#

Pigweed AI summary: The paragraph summarizes the contributing guidelines for Pigweed. It mentions that the project welcomes patches and contributions, but there are guidelines that need to be followed. Before participating, it is important to review the Code of Conduct. The paragraph also provides information on the one-time contributor setup, the presubmission process, the change submission process, and the documentation requirements. It emphasizes the importance of communication and following the project's guidelines.

We’d love to accept your patches and contributions to Pigweed. There are just a few small guidelines you need to follow.

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#

Pigweed AI summary: This document provides an overview of how to contribute to Pigweed, an open-source collection of embedded libraries. It includes instructions for one-time contributor setup, the presubmission process, and the change submission process. The presubmission process involves reaching out to the Pigweed team before making major changes or SEEDs, while the change submission process includes steps such as ensuring correct copyright and license headers, running style and compilation checks, and submitting changes to CI builders for merging. Communication with the Pigweed

Note

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

One-time contributor setup#

Pigweed AI summary: This paragraph outlines the steps required for a one-time contributor setup for Pigweed, a collection of embedded libraries. The steps include signing the Contributor License Agreement, verifying the Git user email, obtaining a login cookie from Gerrit's new-password page, installing the Gerrit Commit Hook, and installing the Pigweed presubmit check hook.

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).
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. Remember to Activate your Pigweed Environment first!

Presubmission process#

Pigweed AI summary: The presubmission process for making or sending major changes or SEEDs in Pigweed involves reaching out to the chat room or mailing list first to ensure the changes make sense for upstream. A design phase is generally gone through before making large changes, and it is recommended to discuss with the team before writing a full SEED. For minor changes that don't fit the SEED process, follow the Small changes guidance and the Change submission process. Skipping communication with the team before doing large amounts of work

Before making or sending major changes or SEEDs, please reach out in our chat room or on the mailing list first to ensure the changes make sense for upstream. We generally go through a design phase before making large changes. See 0001: The SEED Process for a description of this process; but please discuss with us before writing a full SEED. Let us know of any priorities, timelines, requirements, and limitations ahead of time.

For minor changes that don’t fit the SEED process, follow the Small changes guidance and the Change submission process.

Warning

Skipping communicating with us before doing large amounts of work risks accepting your contribution. Communication is key!

Change submission process#

Pigweed AI summary: This section provides guidance on the change submission process for Pigweed, a single git commit also known as a Change List or CL. It advises following the "Small changes" process for a smooth submission and lists steps to take before uploading the change, including reviewing guidance, ensuring correct copyright and license headers, making necessary documentation changes, and running pw_presubmit to detect issues. It also instructs to add a reviewer and address feedback before submitting the change to CI builders for merging.

Note

A change is a single git commit, and is also known as Change List or CL for short.

Tip

Follow Small changes for a smooth submission process.

Go through the Presubmission process and review this document’s guidance.
Ensure all files include the correct copyright and license headers.
Include any necessary changes to the documentation.
Run pw_presubmit to detect style or compilation issues before uploading.
Upload the change with git push origin HEAD:refs/for/main.
Add gwsq-pigweed@pigweed.google.com.iam.gserviceaccount.com as a reviewer. This will automatically choose an appropriate person to review the change.
Address any reviewer feedback by amending the commit (git commit --amend).
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.

Contributor License Agreement#

Pigweed AI summary: Contributions to this project require a Contributor License Agreement, which allows the project to use and redistribute the contributions while the contributor retains copyright. The agreement can be viewed or signed at https://cla.developers.google.com/. A CLA only needs to be submitted once, even if it was for a different project.

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#

Pigweed AI summary: This section provides instructions for setting up the Gerrit Commit Hook, which automatically adds a Change-Id tag to the bottom of each commit message in a Pigweed repository. The instructions differ for Linux/macOS and Windows, with specific commands and file paths provided for each.

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

The command below assumes that your current working directory is the root of your Pigweed repository.

$ 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#

Pigweed AI summary: This paragraph directs the reader to refer to the commit message section of the style guide for instructions on how to format commit messages.

See the commit message section of the style guide for how commit messages should look.

Documentation#

Pigweed AI summary: The Pigweed project requires documentation changes to be made alongside most code changes. To build the documentation, follow the "getting started" guide and run "pw watch out" in the checkout directory. Editing the relevant .rst file and refreshing the browser after the build completes is necessary. Alternatively, the local webserver in watch can be used. All Pigweed changes must include updates to documentation or include a reason for not updating the documentation. It is acceptable to only document new changes in an underdocumented

Most changes to Pigweed should have an associated documentation change.

Building#

Pigweed AI summary: To build the documentation for Pigweed, follow the "getting started" guide and then run "pw watch out" to build the code, run tests, and build docs. After waiting for the build to finish, navigate to the relevant file and edit it as needed. Alternatively, use the local webserver in watch by running "pw watch --serve-docs" and navigating to "http://localhost:8000" in your browser.

To build the documentation, follow the getting started guide so you can build Pigweed. Then:

Change to your checkout directory and . activate.sh if necessary
Run pw watch out to build the code, run tests, and build docs
Wait for the build to finish (see a PASS)
Navigate to <CHECKOUT>/out/docs/gen/docs/html/index.html
Edit the relevant .rst file. Save when ready
Refresh your browser after the build completes

Alternately, you can use the local webserver in watch; this works better for some pages that have external resources: pw watch --serve-docs then navigate to http://localhost:8000 in your browser.

Submission checklist#

Pigweed AI summary: All Pigweed changes must include updates to documentation or include a "No-Docs-Update-Reason" in a Gerrit comment on the CL. It is acceptable to only document new changes in an underdocumented module, but not acceptable to not document new changes because the module has no other documentation.

All Pigweed changes must either:

Include updates to documentation, or
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#

Pigweed AI summary: The Pigweed development process takes place on Gerrit, following the typical Gerrit development workflow. Small changes are encouraged as they are reviewed more quickly, are less likely to introduce bugs, create less wasted work if rejected, are easier to merge, design well, block work less, and are simpler to roll back. A small change is defined as one self-contained change that addresses one thing without breaking other users. Large changes are not necessarily bad, but it is recommended to split them up into smaller,

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

You may add the special address gwsq-pigweed@pigweed.google.com.iam.gserviceaccount.com as a reviewer to have Gerrit automatically choose an appropriate person to review your change.

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.

Small changes#

Pigweed AI summary: Small changes are encouraged in software development because they are easier and quicker to review, less likely to introduce bugs, create less wasted work if rejected, easier to merge, easier to design well, block work less, and simpler to roll back. A small change is defined as a self-contained change that addresses one thing without breaking other users, and is not necessarily defined by the number of lines changed. Related tests, sample usage, and documentation should be included in a small change. Large changes can be split

Small changes are encouraged because they:

Get reviewed more quickly, easily, and thoroughly.
Are less likely to introduce bugs.
Create less wasted work if they are rejected.
Are easier to merge.
Are easier to design well.
Block work less since work can continued while the change is reviewed.
Are simpler to roll back.

A small change can be defined as one self-contained change, which means it makes a mininimal change addressing one thing, without breaking other users. It is not necessarily defined by the number of lines changed. However, as a rule of thumb, 100 changed lines is considered a small change while 1000 lines is too large.

A small change includes related tests, sample usage, and documentation where applicable. It includes everything the reviewer needs to understand the change except for future development.

While reviewers have the discretion to reject a large change, you can work with your reviewer to figure out how to proceed breaking changes apart.

Large changes aren’t bad when deleting or moving files, moving large contents without modifications, adding generated code, or an agreement is reached with the reviewer in advance.

Tip

One way to split up a large change is to split it up by groupings of files in smaller but self-contained changes. See Splitting by Files for examples.

Tip

Separating functional changes from formatting cleanup changes helps create small changes.

Tip

Separating refactoring from features and bug fixes also helps create small changes.

Read Google’s Eng-Practices Small CLs for more details.

Instructions for reviewers#

Pigweed AI summary: The instructions for reviewers include getting the Gerrit Monitor extension, responding within one business day when added to the attention set for a change, removing oneself from the attention set for changes where another person must take action before continuing to review, and leaving a comment when doing so, especially for changes by external contributors who may not be familiar with the process. The response time expectation only applies to Googlers working full-time on Pigweed.

Get the Gerrit Monitor extension.
When added to the attention set for a change, respond within 1 business day:
- Review the change if possible, OR
- If you will not be able to review the change within 1 business day (e.g. due to handling P0s), comment on the change stating so, and reassign to another reviewer if possible.
- The response time expectation only applies to Googlers working full-time on Pigweed.
Remove yourself from the attention set for changes where another person (author or reviewer) must take action before you can continue to review. You are encouraged, but not required, to leave a comment when doing so, especially for changes by external contributors who may not be familiar with our process.

SLO#

Pigweed AI summary: This paragraph states that 90% of changes made by a full-time Googler working on Pigweed are reviewed within one business day.

90% of changes on which a Googler working on Pigweed full-time is added to the attention set as a reviewer get triaged within 1 business day.

Community Guidelines#

Pigweed AI summary: This paragraph states that the project follows Google's Open Source Community Guidelines and the Code of Conduct.

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

Source Code Headers#

Pigweed AI summary: This article discusses the importance of including copyright and license information in every Pigweed file containing source code, including JS/CSS files. It provides Apache headers for C and C++ files, as well as Python and GN files, which must be included in compliance with the Apache License, Version 2.0. The article emphasizes that software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.

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#

Pigweed AI summary: All Pigweed change lists must pass automated builds, tests, and style checks using the pw_presubmit module before being merged upstream. This is done by automated builders before each CL is submitted and in Pigweed's continuous integration infrastructure.

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#

Pigweed AI summary: To run automated presubmit checks on a pending CL, click the "CQ DRY RUN" button in the Gerrit UI. The results will appear in the Tryjobs section, with green indicating passed jobs and red indicating failed jobs. If all checks pass, a "Dry run: This CL passed the CQ dry run." comment will appear, but if any checks fail, a "Dry run: Failed builds:" message will appear and all failures must be addressed before submitting. Pigweed

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#

Pigweed AI summary: Pigweed offers presubmit checks for projects that use its infrastructure, allowing for automatic updates of the Pigweed submodule if tests pass. However, if a project cannot build against Pigweed's latest version, it will remain on a fixed revision until issues are resolved. Pigweed tries to maintain builds for dependent projects, but in some cases, changes may break these projects. In such situations, the downstream project will continue to build against the last working revision of Pigweed until incompatibilities are fixed

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#

Pigweed AI summary: To speed up the review process, you can add "pw_presubmit" as a git push hook by running the command "pw presubmit --install" in Linux or macOS. This will run the presubmit command before every git push. If you need to bypass the presubmit hook, you can use the command "git push origin HEAD:refs/for/main --no-verify". When creating new feature branches, specify the upstream branch to track using the command "git checkout

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

Linux/macOS#

Pigweed AI summary: The article discusses the use of the "pw presubmit" command in Linux and macOS systems. This command is used before every "git push" and can be installed using the "pw presubmit --install" command. The article also provides a demo of the "pw presubmit" command and explains how to bypass the presubmit hook if needed.

$ pw presubmit --install

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

$ pw presubmit

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

Presubmit and branch management#

Pigweed AI summary: This paragraph provides guidance on presubmit and branch management when creating new feature branches. It advises specifying the upstream branch to track and provides an example command for doing so. By tracking an upstream branch, the presubmit tool will only run checks on modified files rather than the entire repository.

When creating new feature branches, make sure to specify the upstream branch to track, e.g.

$ git checkout -b myfeature origin/main

When tracking an upstream branch, pw presubmit will only run checks on the modified files, rather than the entire repository.

Presubmit flags#

Pigweed AI summary: The paragraph describes the flags that can be used with the "pw presubmit" command. These flags include options for specifying the base commit, running presubmit on all files, excluding certain paths, continuing instead of aborting on errors, specifying the output directory and package root directory, deleting the presubmit output directory, choosing a specific presubmit program or providing explicit steps, and installing presubmit as a Git pre-push hook.

pw presubmit can accept a number of flags

-b commit, --base commit: Git revision against which to diff for changed files. Default is the tracking branch of the current branch. Set commit to “HEAD” to check files added or modified but not yet commited. Cannot be used with –full.
--full: Run presubmit on all files, not just changed files. Cannot be used with –base.
-e regular_expression, --exclude regular_expression: Exclude paths matching any of these regular expressions, which are interpreted relative to each Git repository’s root.
-k, --keep-going: Continue instead of aborting when errors occur.
--output-directory OUTPUT_DIRECTORY: Output directory (default: <repo root>/out/presubmit)
--package-root PACKAGE_ROOT: Package root directory (default: <output directory>/packages)
--clear, --clean: Delete the presubmit output directory and exit.
-p, --program PROGRAM: Which presubmit program to run
--step STEP: Provide explicit steps instead of running a predefined program.
--install: Install the presubmit as a Git pre-push hook and exit.