| <?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 Check-In Privileges</h2> |
| <p>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.</p> |
| |
| <p>The sponsor arranges a copy of the committer agreement to be sent to the contributor. |
| Once the contributor sends a copy of the signed agreement to Apple, she or he receives check-in access.</p> |
| |
| |
| <h2>Becoming a Reviewer</h2> |
| <p>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.</p> |
| |
| <p>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 or she will defer to another reviewer.</p> |
| <?php |
| include("../footer.inc"); |
| ?> |