b01dc31b15d8213bb1293d38be1a0d6e08481ac2
[WebKit.git] / WebKitSite / coding / contributing.html
1 <?php
2     $title="Contributing Code";
3     $extra_head_content = <<<END
4 <style type="text/css">
5 img {
6     border:1px solid black
7 }
8 </style>
9
10
11 END;
12
13     include("../header.inc");
14 ?>
15 <h2>Contributing Code</h2>
16 <p>This page describes how to contribute changes to the WebKit
17 source control repository.
18 The WebKit project maintains several <a href="scripts.html">scripts</a>
19 to assist you. This page assumes you already know how to
20 <a href="/building/checkout.html">check out</a> and
21 <a href="/building/build.html">build</a> the code.</p>
22
23 <h3>Overview</h3>
24 <p>Below are the recommended steps.
25 Later sections of this page explain each step in more detail.
26 </p>
27
28 <ol>
29     <li>Choose or create a <a href="#bugreport">bug report</a> to work on.</li>
30     <li><a href="#writecode">Develop</a> your changes.</li>
31     <li>Make sure your changes meet the <a href="/coding/coding-style.html">code
32         style guidelines</a>. The <tt>check-webkit-style</tt> script may be of
33         help.</li>
34     <li>Run the layout tests using the <tt>run-webkit-tests</tt> script and make sure they all pass.
35         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>
36     <li>Add any <a href="#newfiles">new files</a> to your working directory.</li>
37     <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>
38     <li>Create the patch using the <tt>svn-create-patch</tt> script.</li>
39     <li><a href="#submit">Submit</a> your patch for review to
40         <a href="https://bugs.webkit.org/">bugs.webkit.org</a>.</li>
41     <li>Make any changes recommended by the reviewer.</li>
42     <li>Once reviewed, ask someone to land your patch or mark it for <a href="#commitqueue">automated commit</a>.
43     <li>Please watch for any regressions it may have caused (hopefully none)!</li>
44 </ol>
45
46 <p>More detail about these steps is below.</p>
47
48 <h3 id="bugreport">Choose a bug report</h3>
49 <p>The <a href="https://bugs.webkit.org/">bugs.webkit.org</a> database
50 is the central point of communication for contributions to WebKit.
51 Nearly every contribution corresponds to a bug report there.
52 Note that WebKit uses bug reports to track all types of code changes
53 and not just bug fixes.
54 </p>
55
56 <p>Choose a bug report to work on. You can also create a new report.
57 Be sure to search the database before creating new reports to avoid
58 duplication.</p>
59
60 <p>After choosing a bug report, follow the
61 WebKit <a href="/quality/lifecycle.html">bug life cycle</a> guidelines
62 for the report. For example, it is often good practice to comment
63 in a report if you are working on that issue. If your change
64 may be controversial, you may want to check in advance with the
65 <a href="http://lists.webkit.org/mailman/listinfo/webkit-dev">
66 webkit-dev</a> mailing list.</p>
67
68 <h3 id="writecode">Develop your changes</h3>
69
70 <p>If you make substantive changes to a file, you may wish to add a
71 copyright line for yourself or for the company on whose behalf you
72 work. Below are sample copyright lines for an individual contributor
73 and a company:
74
75 <p><tt>Copyright (C) 2010 John Smith (jsmith@example.com)</tt></p>
76 <p><tt>Copyright (C) 2010 Company Inc. All rights reserved.</tt></p>
77
78 <p>In addition, make sure that any new source code and script files
79 you introduce contain license text at the beginning of the file.
80 If you are the author of a new file, preferred license text to include
81 can be found here:
82 <a href="http://trac.webkit.org/browser/trunk/WebKit/LICENSE">WebKit/LICENSE</a>.
83 (The "Original Format" link at the bottom of the page contains text
84 that can be cut and pasted more easily.) Simply replace the copyright
85 line with your own information, for example as suggested above.
86
87 <h3>Code Style Guidelines</h3>
88 <p>Patches must comply with the <a href="/coding/coding-style.html">code style guidelines</a>.
89 Some older parts of the codebase do not follow these guidelines.
90 If you are modifying such code, it is generally best to clean it up
91 to comply with the current guidelines. An exception is legacy components,
92 which should not be cleaned up.</p>
93
94 <h3>Regression tests</h3>
95 <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.
96 All tests must pass.  Patches will not be landed in the tree if they break existing layout tests.</p>
97
98 <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,
99 that patch should also include the addition of a regression test that would fail without the patch and succeed with the patch.
100 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
101 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
102 why a new test isn't necessary to the reviewer.</p>
103
104 <p>Information on writing a layout test as well as what needs to be done if you've made changes to JavaScriptCore
105 can be found on the <a href="/quality/testwriting.html">testing page</a>.</p>
106
107 <h3 id="newfiles">Add new files to your working directory</h3>
108 <p>If your changes include adding new files (like new layout tests),
109 use the <tt>svn add</tt> command to mark these files for addition to the
110 repository. If you do not do this, the new files will be missing from
111 the patch file you generate below.</p>
112
113 <p>You can learn more about Subversion commands like <tt>svn add</tt>
114 from the online book <a class="book" href="http://svnbook.red-bean.com/">
115 Version Control with Subversion</a> and by using the <tt>svn help</tt>
116 command.</p>
117
118 <h3 id="changelogs">ChangeLog files</h3>
119 <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>
120
121 <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>, note that you can use <tt>--bug</tt> flag).  (You should set EMAIL_ADDRESS and CHANGE_LOG_NAME in your environment if you will be running this script frequently.)</p>
122
123 <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>
124
125 <h3>Create the patch</h3>
126 <p>WebKit uses <tt>svn-create-patch</tt> to create patches. The
127 <tt>svn-create-patch</tt> script is a small wrapper around Subversion's
128 <tt>diff</tt> command that better handles moved, added, and deleted files.
129 This command is best run from the top level of your checkout
130 to make sure no changes are left out of your patch. It is not necessary to
131 break a patch into multiple files.</p>
132
133 <p>The <tt>svn-create-patch</tt> script does not create a file automatically.
134 You need to redirect the output yourself using something like--</p>
135 <p class="code">svn-create-patch > MyExcellentPatch.txt</p>
136
137 <h3 id="submit">Submit your patch</h3>
138 <p>Submit your patch by clicking the "Add an attachment" link in the
139 <a href="#bugreport">bug report</a> you chose for your contribution.</p>
140
141 <p><img src="images/contribute_add_attachment.png"
142 alt='Bugzilla "Add an attachment" link'></p>
143
144 <p>Complete the attachment form by doing at least the following:
145 <ol>
146     <li>Browse to your patch file in the File field.</li>
147     <li>Type a brief description in the Description field, for example
148         "Proposed patch."</li>
149     <li>Check the "patch" checkbox (see picture below).</li>
150     <li>Select the question mark "?" in the "review" pull-down
151         (see picture below).</li>
152     <li>Click Submit at the bottom.</li>
153 </ol>
154 </p>
155
156 <p><img src="images/contribute_mark_review.png"
157 alt="Bugzilla patch-submission options"></p>
158
159 <p>The patch checkbox and the <tt>review:?</tt> flag signal to
160 WebKit reviewers that your patch is ready for review.
161 Setting the review flag also sends an automatic e-mail to the
162 <a href="http://lists.webkit.org/mailman/listinfo/webkit-reviews">
163 webkit-reviews</a> mailing list which some reviewers subscribe to.
164 </p>
165
166 <h3>Respond to reviewers</h3>
167 <p>A WebKit reviewer must approve your patch before WebKit can accept
168 it into the source control repository.
169 A reviewer will typically either approve your patch
170 (by responding with an <tt>r=me</tt> in the bug report and marking the patch <tt>review:+</tt>) or request revisions
171 to your patch (and mark the patch <tt>review:-</tt>). In rare cases a patch may be permanently rejected, meaning that the reviewer
172 believes the feature should never be committed to the tree. The review process can consist of multiple iterations between you and
173 the reviewer as you submit revised patches.</p>
174
175 <h3 id="landing">Landing in the tree</h3>
176 <p>Once a patch is approved, you should ask <a href="https://lists.webkit.org/mailman/roster.cgi/webkit-committers">someone with commit access</a> to land your patch. Alternatively you can request that your patch be committed by our <a href="#commitqueue">commit bot</a>.</p>
177
178 <h4>Keeping the tree green</h4>
179 <p>In either case, 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>
180
181 <p>Changes should succeed on all platforms, but it can be difficult to test on every platform WebKit supports.  Be certain that your change does not introduce new test failures on the high-traffic Mac or Windows ports by comparing the list of failing tests before and after your change.  Your change must at least compile on all platforms.</p>
182
183 <h4 id="commitqueue">Optional: Use of the WebKit Commit Bot</h4>
184 <p>WebKit provides an automated system (commit-queue) for landing patches for any who would like to use it.  To use the commit-queue, set the <tt>commit-queue:?</tt> flag on your patch.  A committer will set <tt>commit-queue:+</tt> and an automated process will download, build, run the layout tests, and submit your patch on your behalf.  If the <a href="http://build.webkit.org/">WebKit buildbots</a> are passing, your patch should be landed within 15 minutes after <tt>commit-queue:+</tt> is set. See the <a href="https://trac.webkit.org/wiki/CommitQueue">commit-queue documentation</a> for more information.</p>
185
186 <h2>Obtaining Commit and Review Privileges</h2>
187 <p>Our <a href="commit-review-policy.html">Committer and Reviewer policy</a> provides details on obtaining commit and review privileges.</p>
188
189 <?php
190     include("../footer.inc");
191 ?>