WebKitSite/coding/contributing.html

<?php 
    $title="Contributing Code";
    include("../header.inc"); 
?>
<h2>Contributing Code</h2>
<p>Contributing code to the WebKit project is a straightforward process.
Once you have the code <a href="/building/checkout.html">checked out</a>, <a href="/building/build.html">built</a>, and made your changes, you'll need to do a few things in order to get it landed in the tree:</p>
<ol>
    <li>Make sure your changes meet the <a href="/coding/coding-style.html">code style guidelines</a>.</li>
    <li>Run the layout tests using the <tt>run-webkit-tests</tt> script and make sure they all pass.
        See the <a href="/quality/testwriting.html">testing page</a> for more information, as well as what you need to do if you've modified JavaScriptCore.</li>
    <li>Add any new files and layout tests to Subversion using the <tt>svn add</tt> command.</li>
    <li>Prepare a changelog entry. The <tt>prepare-ChangeLog</tt> script will create a stub entry for you.</li>
    <li>Create the patch using the <tt>svn-create-patch</tt> script.</li>
    <li>Upload the patch for review. In Bugzilla, be sure to set the <tt>review:?</tt> flag.</li>
    <li>Make any changes recommended by the reviewer.</li>
    <li>Once reviewed, get your patch landed in the tree and watch for any regressions it may have caused (hopefully none)!</li>
</ol>


<h3>Code Style Guidelines</h3>
<p>In order for your patch to be landed, it's necessary that it comply to the <a href="/coding/coding-style.html">code style guidelines</a>.
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.</p>

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

<p>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.</p>

<p>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 <a href="/quality/testwriting.html">testing page</a>.</p>

<h3>Adding new files</h3>
<p>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 <tt>svn add</tt> command.
More information on Subversion commands can be found via <tt>svn help</tt> or the <a href="http://svnbook.red-bean.com/">Version Control with Subversion</a> online book.</p>

<h3>ChangeLog</h3>
<p>All patches require an entry to the ChangeLog. The <tt>prepare-ChangeLog</tt> 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.</p>

<h3>Create the patch</h3>
<p>WebKit uses the <tt>svn-create-patch</tt> script to create patches. This script supplements Subversion's <tt>diff</tt> 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.</p>

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

<h3>Patch review</h3>
<p>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 <tt>review:?</tt>. The reviewer will typically either approve the patch
(by responding with an <tt>r=me</tt> in the bug report or in e-mail and marking the patch <tt>review:+</tt>) or request revisions
to the patch (and mark the patch <tt>review:-</tt>). 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.</p>

<h3>Landing in the tree</h3>
<p>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.</p>

<h2>WebKit Scripts</h2>
<p><tt>WebKitTools/Scripts</tt> 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.</p>
<p>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.</p>

<h2>Obtaining Commit and Review Privileges</h2>
<p>Our <a href="commit-review-policy.html">Committer and Reviewer policy</a> provides details on obtaining commit and review privileges.</p>

<?php
    include("../footer.inc");
?>