Contributing Code

Submitting Code Changes

Contributing code to the WebKit project is a straightforward process. One you have checked out and built the code, you can make changes to it and then produce a patch file that contains only the differences between the current version of WebKit and your version of WebKit with your code changes.

The svn-create-patch script, found in WebKitTools/Scripts along with the other WebKit scripts, should be used to produce patches. It does a svn diff operation, handling files added and removed from the repository, and working around path problems that normally prevent some patches created with svn diff from being applied by patch. Use it to create a patch as follows:

WebKitTools/Scripts/svn-create-patch > MyExcellentPatch.txt

It's handy to put the WebKitTools/Scripts directory in your shell path so you can type commands like svn-create-patch without specifying the path to the script.

The svn-apply and svn-unapply scripts are handy for applying patches to a tree, and rolling patches out of a tree. They go beyond the capabilities of the patch tool by handling files added and removed from the repository.

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: ?. This will automatically send mail to webkit-reviews@opendarwin.org on your behalf. The WebKit Bug Life Cycle page has more information about the stages of a WebKit Bugzilla bug.

Make sure that your patch includes a ChangeLog entry, meets the coding style guidelines, and has received sufficient testing. Bug fixes should include a new WebKit or JavaScriptCore test.

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.

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.

In addition you must run the regression tests. The command to do that is:

WebKitTools/Scripts/run-webkit-tests

It's handy to put the WebKitTools/Scripts directory in your shell path so you can type commands like run-webkit-tests without specifying the path to the script.

Only if all layout tests pass (or if justification can be made for changing the expected results of the tests) will the patch be allowed in the tree. It is the reviewer's responsibility to double-check that you have run the regression tests before signing off on the patch.

If you are modifying JavaScriptCore there is an additional test suite that you need to run. For more details on the required testing you must do before landing a patch, see this document.

Once a patch has been reviewed, there are two options for getting it into the tree. If you have check-in privileges, you can land the patch immediately once it has been reviewed. If you do not have check-in privileges, then it is the reviewer's responsibility to land the patch in the tree.

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.

Obtaining Check-In Privileges

Contributors with a proven track record of good patch submissions and that have demonstrated an ability to work well with the community can obtain check-in privileges to the WebKit source tree. In order to obtain this check-in access, the contributor must find a reviewer who will act as a sponsor.

The contributor must then sign and submit the contributor agreement (link forthcoming) to Apple in order to be granted check-in access.

Becoming a Reviewer

A contributor with check-in access may also become a reviewer. In order to become a reviewer, the current reviewers must agree that the contributor is effectively functioning as an expert in a particular area of the code and is qualified to review patches submitted in that area.

Reviewers are always responsible only for areas of code in which they are knowledgeable. If the reviewer does not feel qualified to handle a particular patch, then he will defer to another reviewer.