<?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 change log entry. You may have to add entries to multiple ChangeLogs. The <tt>prepare-ChangeLog</tt> script will create stub entries for you.  See the <a href="#changelogs">paragraph about ChangeLogs</a> below.</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>

<a name="changelogs"><h3>ChangeLog files</h3></a>
<p>ChangeLogs are simple text files which provide historical documentation for all changes to the WebKit project.  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.  The first line contains the date, your full name, and your email address.  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>

<p>There is one ChangeLog per top-level directory, if you changed code and tests you will need to edit at least two ChangeLogs. The <tt>prepare-ChangeLog</tt> script will create a stub entries for you.  You should edit these stubs to describe your change, including the full url to the bug (<a href="http://trac.webkit.org/changeset/43259">example entry</a>).  (You should set EMAIL_ADDRESS and CHANGE_LOG_NAME in your environment if you will be running this script frequently.)</p>

<p>The line WARNING: NO TEST CASES ADDED OR CHANGED appears if prepare-ChangeLog did not detect the addition of test cases.  If your patch does not require test cases (or test cases are not possible), you should include a line stating such.  Otherwise all changes require test cases which should be mentioned in the ChangeLog.</p>

<h3>Create the patch</h3>
<p>WebKit uses the <tt>svn-create-patch</tt> script to create patches.  <tt>svn-create-patch</tt> is just a small wrapper around Subversion's <tt>diff</tt> command which knows how to better handle 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.  You can watch the tree at <a href="http://build.webkit.org">build.webkit.org</a> to make sure your patch builds and passes tests on all platforms.
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");
?>