Contributing Code

Contributing code to the WebKit project is a straightforward process. Once you have the code checked out, built, and made your changes, you'll need to do a few things in order to get it landed in the tree:

  1. Make sure your changes meet the code style guidelines.
  2. Run the layout tests using the run-webkit-tests script and make sure they all pass. See the testing page for more information, as well as what you need to do if you've modified JavaScriptCore.
  3. Add any new files and layout tests to Subversion using the svn add command.
  4. Prepare a changelog entry. The prepare-ChangeLog script will create a stub entry for you.
  5. Create the patch using the svn-create-patch script.
  6. Upload the patch for review. In Bugzilla, be sure to set the review:? flag.
  7. Make any changes recommended by the reviewer.
  8. Once reviewed, get your patch landed in the tree and watch for any regressions it may have caused (hopefully none)!

Code Style Guidelines

In order for your patch to be landed, it's necessary that it comply to the code style guidelines. There are some older parts of the codebase that do not always follow these guidelines. If you come across code like this, it's generally best to clean it up to comply with the new guidelines.

Regression tests

Once you have made your changes, you need to run the regression tests, which is done via the run-webkit-tests script. All tests must pass. Patches will not be landed in the tree if they break existing layout tests.

For any feature that affects the layout engine, a new regression test must be constructed. If you provide a patch that fixes a bug, that patch should also include the addition of a regression test that would fail without the patch and succeed with the patch. If no regression test is provided, the reviewer will ask you to revise the patch, so you can save time by constructing the test up front and making sure it's attached to the bug. If no layout test can be (or needs to be) constructed for the fix, you must explain why a new test isn't necessary to the reviewer.

Information on writing a layout test as well as what needs to be done if you've made changes to JavaScriptCore can be found on the testing page.

Adding new files

New files and layout tests must be added to Subversion or else they won't be included in your patch. This is done with the svn add command. More information on Subversion commands can be found via svn help or the Version Control with Subversion online book.

ChangeLog

All patches require an entry to the ChangeLog. The prepare-ChangeLog script will create a basic entry containing a list of all files that have been changed. Use this to write up a brief summary of the changes you've made. Don't worry about the "Reviewed by NOBODY (OOPS!)" line, the person landing your patch will fill this in.

Create the patch

WebKit uses the svn-create-patch script to create patches. This script supplements Subversion's diff command to better handle things like moved, added, and deleted files. This command is best run from the top level of your checkout to make sure no changes are left out of your patch. It is not necessary to break a patch into multiple files.

svn-create-patch does not create a file automatically, you need to redirect the output yourself using something like: svn-create-patch > MyExcellentPatch.txt

Patch review

Once you have a patch file, it must be reviewed by one of the approved WebKit reviewers. To request a review, attach the patch to the bug report, and mark the patch with the flag review:?. The reviewer will typically either approve the patch (by responding with an r=me in the bug report or in e-mail and marking the patch review:+) or request revisions to the patch (and mark the patch review:-). In rare cases a patch may be permanently rejected, meaning that the reviewer believes the feature should never be committed to the tree. The review process can consist of multiple iterations between you and the reviewer as revisions are made to your patch.

Landing in the tree

Once a patch is approved, someone with commit access will land your patch. Your responsibility for the patch does not end with the patch landing in the tree. There may be regressions from your change or additional feedback from reviewers after the patch has landed. It is your responsibility to be available should regressions arise and to respond to additional feedback that happens after a check-in.

WebKit Scripts

WebKitTools/Scripts contains a number of scripts to help make life easier when submitting a patch. All scripts mentioned on this page (and on the rest of the site as well) are located here unless otherwise mentioned.

It's handy to put this directory in your shell path so you can just type the commands without having to specify the path to the script each time.

Obtaining Commit and Review Privileges

Our Committer and Reviewer policy provides details on obtaining commit and review privileges.