Skip to content

Contribute

Jump to bottom
Russ Cox edited this page Nov 5, 2025 · 12 revisions

This document explains how to contribute changes to RE2. It assumes you have installed RE2 using the installation instructions.

Discuss your design

RE2 welcomes submissions but please let everyone know what you're working on if you want it to become part of the main repository.

Before undertaking to write something new for RE2, send mail to the mailing list to discuss what you plan to do. This gives everyone a chance to validate the design, helps prevent duplication of effort, and ensures that the idea fits inside the goals for the language and tools. It also guarantees that the design is sound before code is written; the code review tool is not the place for high-level discussions.

In short, send mail before you code. And don't start the discussion by mailing a change list!

Testing

Before sending code out for review, run all the tests for the whole tree to make sure the changes don't break other packages or programs:

$ cd your_re2_root
$ make test

The test output should end with the line ALL TESTS PASSED. (Make may print an rm command after that.)

If you prefer, you can use CMake or Bazel. See README.md for instructions.

You should also add tests covering the code you are adding. If this is a bug fix, add a test that checks the bug is really fixed.

Code review

Changes to RE2 must be reviewed before they are submitted, no matter who makes the change. (In exceptional cases, such as fixing a build, the review can follow shortly after submitting.) The code review process is managed by using git to submit to the code review server.

Configuring your Git client

Start by double-checking that you have cloned your Git repository from GitHub, not from Gerrit.

(We used to use the Gerrit repo at https://code.googlesource.com/re2 and used Gerrit code reviews, but now GitHub is the source of truth and we use GitHub PRs.)

$ git config remote.origin.url
https://github.com/google/re2

If you don't have them set globally already, set the default user name and email address to use in commits.

$ git config user.name "Grace R. Emlin"
$ git config user.email [email protected]

Creating a change

After checking out the main branch, make whatever changes you need to make, and commit them with git add and git commit.

$ git add re2/re2.cc
$ git commit

The first line of the commit description is conventionally a one-line summary of the change and is used as the subject for code review mail; the rest of the description elaborates. For example:

fix bug in simplifier

See Bimmler and Shaney, ``Extreme automata,'' J. Applied Math 3(14).
Fixes #159.

The special sentence “Fixes #159.” associates the change with issue 159 in the RE2 issue tracker. When this change is eventually submitted, the issue tracker will automatically mark the issue as fixed.

If you need to revise the change after git commit, use git commit --amend to rewrite the commit instead of creating a new commit.

$ git add re2/re2.h
$ git commit --amend

Synchronize your client

While you were working, others might have submitted changes to the repository. To update your client, run

$ git fetch origin
$ git rebase origin/main

If files you were editing have changed, Git does its best to merge the remote changes into your local changes. It may leave some files to merge by hand. After making any necessary edits, commit them using git commit --amend, as usual.

Send a pull request

See GitHub's documentation for how to create a pull request.

Sign the CLA

You need to complete one of the contributor license agreements:

  • If you are the copyright holder, you will need to agree to the individual contributor license agreement, which can be completed online.

  • If your organization is the copyright holder, the organization will need to agree to the corporate contributor license agreement. (If the copyright holder for your code has already completed the agreement in connection with another Google open source project, it does not need to be completed again.)

This rigmarole needs to be done only for your first submission.

Copyright

Files in the RE2 repository don't list author names, both to avoid clutter and to avoid having to keep the lists up to date. Instead, your name will appear in the Git change log.

Code that you contribute should use the standard copyright header:

// Copyright 2010 The RE2 Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
Clone this wiki locally