Contribute
This document explains how to contribute changes to RE2. It assumes you have installed RE2 using the installation instructions.
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!
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.)
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.
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.
Start by double-checking that you have cloned your Git repository from https://code.googlesource.com/re2, not from GitHub. That server is the code review server, running Gerrit.
$ git config remote.origin.url https://code.googlesource.com/re2
Next, configure a command shortcut git upload.
$ git config alias.upload 'push origin HEAD:refs/for/main'
Next, install the Gerrit commit hook, which adds a Change-Id line to any commit you make.
$ cd .git/hooks $ ln -s ../../lib/git/commit-msg.hook commit-msg
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 gre@swtch.com
The code review process requires that each change live in a branch with exactly one commit beyond the main branch.
Start by switching to a new branch; you can choose any name. In this example we'll use bugfix
$ git checkout -b bugfix
Now 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
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.
In order to upload a change, you must log in to the code review site, obtain a password, and store that password where Git can find it. You only need to do this for your first change. Subsequent changes will use the same password.
Open your web browser and log in to https://code-review.googlesource.com/. Visit https://code-review.googlesource.com/#/settings/http-password and click “Obtain Password.” After selecting which Google Account to create a Git password for, you should end up on a page with a password and instructions for installing that password for use by Git. Follow those instructions.
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.
When the change is ready, upload it using git upload, which you defined earlier.
$ git upload
Uploading the change will trigger mail to the RE2 developers that a new change is ready.
Running git upload will send an email to you and the reviewers asking them to visit the issue's web page and make coments on the change. When done, the reviewer sends comments back using the web page.
You will probably revise your code in response to the reviewer comments. When you have revised the code and are ready for another round of review, update the change as before, with git add and git commit --amend, and then re-run git upload.
In addition to the git upload, you should visit the code review web page and reply to the comments, letting the reviewer know that you've addressed them or explain why you haven't.
Once your line-by-line comment replies are ready and you've uploaded the new version, click “Reply” and enter “PTAL” (please take another look) as the message.
The reviewer can comment on the new copy, and the process repeats. The reviewer approves the change by replying with a +1. Trusted reviewers can give the change a +2 score and submit it by clicking the “Submit” button. When that happens, you get an email that the code has been submitted.
The change is submitted with additional metadata in the change description, so you will not be able to merge it with your work directly. Instead, switch back to the main branch, discard the old branch, and pull your work back into main.
$ git checkout main $ git branch -d bugfix $ git pull
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.