How to Contribute Code Patches to libvpx

Contributing code to the libvpx project—the reference software codec library for VP8 and VP9 video formats—involves a structured peer-review workflow. This guide provides a clear, step-by-step overview of how to sign the required contributor agreement, set up your local development environment, submit your code patches to the Gerrit review system, and work with maintainers to get your changes successfully merged.

Step 1: Sign the Contributor License Agreement

Before you can submit any code to libvpx, you must sign the Google Contributor License Agreement (CLA). This can be completed online through the Google Developers website. Ensure that the email address associated with your Git commits matches the email used to sign the CLA.

Step 2: Clone the Repository

The official source code for libvpx is hosted on Google’s Git servers. Clone the repository to your local machine using the following command:

git clone https://chromium.googlesource.com/webm/libvpx

Step 3: Install the Gerrit Commit-Msg Hook

The libvpx project uses Gerrit for code review. Gerrit requires a unique Change-Id tag in the footer of every commit message. You can automate the generation of this ID by downloading the standard Gerrit commit-msg hook into your local repository:

cd libvpx
curl -Lo .git/hooks/commit-msg https://gerrit-review.googlesource.com/tools/hooks/commit-msg
chmod +x .git/hooks/commit-msg

Step 4: Create a Branch and Make Your Changes

Create a new local branch for your development work to keep your workspace organized:

git checkout -b my-bugfix-branch

Implement your code changes, ensuring they adhere to the project’s coding style (standard C code, consistent indentation, and proper formatting). Run local tests to verify that your changes do not break existing functionality.

Step 5: Commit Your Changes

Commit your modifications locally. Your commit message should feature a concise one-line summary, followed by a blank line and a detailed description of the changes.

git commit -a

The commit-msg hook will automatically append a line containing the Change-Id to your commit message when you save and exit the editor. Do not modify or delete this ID.

Step 6: Upload the Patch for Review

Push your committed patch to the Gerrit code review server. By default, development occurs on the master branch, so you will push to refs/for/master:

git push origin HEAD:refs/for/master

Once uploaded, Gerrit will output a URL where you can view your patch, add reviewers, and track the progress of the review.

Step 7: Address Review Feedback

Project maintainers will review your patch and may request changes or optimizations. To update your submission:

  1. Make the requested edits in your local branch.
  2. Stage the changes and amend your previous commit: git commit -a --amend (this preserves the original Change-Id).
  3. Push the updated commit back to Gerrit: git push origin HEAD:refs/for/master

Gerrit will automatically group the new upload as a new patch set under the same change entry. Once your code receives approval (a “+2” score) and passes automated build tests, a repository maintainer will merge the patch into the main code tree.