Contributing guide#

Thank you for your interest in improving Upstream Pigweed! This guide quickly walks you through the end-to-end contribution process.

Tip

If you don’t have a particular contribution in mind, check out our good first issues and bring it home changes. The bring it home changes are incomplete changes that we would be happy to merge but need more work before we can accept them.

Contact us#

If you ever need help, please don’t hesitate to contact us:

Expectations#

This is what we expect from all contributors. Please don’t send us code if you can’t commit to all of these expectations. You’re welcome to create an issue instead.

Community guidelines#

We expect everyone who interacts with the project to respect our Code of conduct and Google’s Open Source Community Guidelines.

Complete solutions#

Contributions are expected to be complete solutions accompanied by documentation, tests, and support for our primary build systems.

Support for primary build systems#

Patches must include support for our three primary build systems: Bazel, GN, and CMake. Soong is optional but appreciated. We understand that not everyone has experience with all three builds; but for most patches following the pattern of existing code is enough. If not, we can help on chat.

Build systems reference provides the common commands that you need when working with each build system.

Communications around major changes#

Before making major changes or SEEDs, please contact us. We always have design discussions before making large changes.

Requirements#

Your Development host must meet these requirements:

  • Operating system: Linux has the best support, then macOS, then Windows. See Support notes.

  • Disk space: After a full build, the Pigweed repository takes up about 10 gigabytes of disk space. The repo is large because we hermetically download many different cross-platform toolchains and compile the code for many hardware architectures.

Setup#

Contributor license agreement#

Sign the Google Open Source Contributor License Agreement (CLA). If you’ve already signed it for another Google project, you don’t need to sign it again.

All Pigweed contributors must sign the CLA. You (or your employer) retain the copyright to your contribution. The CLA simply gives us permission to use and redistribute your contributions as part of the project.

Install developer tools#

A few tools must be installed globally on your development host:

  1. Complete the first-time setup process.

  2. Install Bazelisk.

If you’re a Googler working on a Google-owned development host, there is some extra required setup. See Pigweed onboarding for Googlers.

Clone the repo#

  1. Clone the upstream Pigweed repository:

    $ git clone https://pigweed.googlesource.com/pigweed/pigweed

  2. cd into the repo:

    $ cd pigweed

Gerrit setup#

Set up your development host to be able to push code to our Gerrit instance:

  1. Obtain a login cookie from Gerrit’s new password page. Make sure to sign in with the email address that you used for the Contributor license agreement.

  2. Install the Gerrit commit hook so that a Change-Id is automatically added to the bottom of all of your commits messages.

    $ 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

    $ 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

    $ git rev-parse --git-dir > gitrepopath.txt & set /p "g="< gitrepopath.txt & del gitrepopath.txt & call set "f=%g%/hooks" & call mkdir "%f%" & call curl -Lo "%f%/commit-msg" https://gerrit-review.googlesource.com/tools/hooks/commit-msg

Create your change#

Differences between Gerrit and GitHub#

We do all of our code reviews on Gerrit. Our GitHub mirror is read-only. Gerrit’s code review workflow is different than GitHub. See Basic Gerrit walkthrough for GitHub users and Changes.

Pushing changes#

Always use this command to push up your code to Gerrit:

$ git push origin HEAD:refs/for/main

Amending changes#

When you need to update the code in your change, use --amend:

$ git commit --amend

This workflow is required because each commit past main is treated as a separate change.

If you use incremental commits to help keep track of your work, you will eventually need to use a rebase workflow to merge all of the commits into a single commit:

$ git rebase -i HEAD~10 # last 10 commits
# An interactive editor will open. Mark each of your incremental
# commits with `f` or `fixup` to merge them into the first commit.

Commit message conventions#

Follow our Commit message style.

We use a specific structured format for commit titles. We have a presubmit check that enforces our commit title style.

Code review#

Dry run the presubmit checks#

If you want to dry run Pigweed’s presubmit checks, ask a committer to kick them off for you. Only committers can start a dry run.

The presubmit checks are our suite of automated builds, tests, linters, and formatters. When you attempt to merge your change, all of the presubmit checks must pass. Dry running the presubmit checks lets you find and fix issues early.

Selecting reviewers#

Look for OWNERS files near the code that you’ve contributed. Those people should be your reviewers. If you can’t find owners, add gwsq-pigweed@pigweed.google.com.iam.gserviceaccount.com as a reviewer. This will automatically choose an appropriate person to review the change.

Merging your change#

You need 2 Pigweed committers to approve your change. Only committers can merge changes.

Feedback#

Thank you very much for contributing to Pigweed! And welcome to the community :)

If you have suggestions on how we can improve our contribution process you are welcome to send us feedback using the usual channels.

On this page