Reviewed by Beth.
[WebKit-https.git] / WebKitSite / quality / lifecycle.html
1 <?php
2         $title = "WebKit Bug Life Cycle";
3         include("../header.inc");
4 ?>
5 <h2>WebKit Bug Life Cycle</h2>
6
7 <h3>Introduction</h3>
8
9 <p>This document describes the life cycle of a bug in the WebKit open-source project. In most ways
10 this is the same as the life cycle of a bug in any Bugzilla project. The Bugzilla site also includes 
11 <a href="http://bugzilla.opendarwin.org/page.cgi?id=fields.html#status">more details</a> about
12 the life cycle of Bugzilla bugs.<p>
13
14 <p>Joost de Valk (AlthA on the <a href="../contact.html">#webkit IRC channel</a>, homepage at 
15 <a href="http://www.joostdevalk.nl/">www.joostdevalk.nl</a>) has volunteered to answer questions
16 about the WebKit bug life cycle. You can reach him on IRC or via email at webkit at joostdevalk dot nl.
17
18 <h3>Fresh, Unconfirmed Bugs</h3>
19
20 <p>A freshly-created bug starts out in state <tt>UNCONFIRMED</tt>. Often it is in component <tt>New Bugs</tt>, but
21 some bugs will be given an initial component in the initial <a href="reporting.html">bug-reporting step</a>.</p>
22
23
24 <h3><a name="confirming"></a>Confirming Bugs</h3>
25
26 <p>The next step is for someone with Bugzilla <tt>canConfirm</tt> privileges to review the unconfirmed bug and
27 decide whether it has enough useful information to move forward. The possible changes to the bug at this step include the following:</p>
28
29 <ul>
30 <li>Resolution changed to <tt>DUPLICATE</tt> if the bug is determined to have the same cause as a bug reported earlier.</li>
31 <li>Resolution changed to <tt>WORKSFORME</tt> if the bug seems to not be present in the latest sources.</li>
32 <li>Resolution changed to <tt>INVALID</tt> if the bug does not describe a problem with WebKit.</li>
33 <li>Resolution changed to <tt>WONTFIX</tt> in the rare case that the bug seems valid but there's a specific reason why it 
34 should not be fixed in WebKit (usually this would be a cross-browser compatibility issue).</li>
35 <li>Comments/questions added if the bug does not have enough information to move forward.</li>
36 <li>Status changed to <tt>NEW</tt> if the bug is reproducible or otherwise has enough information to move forward. Along with changing the status,
37 the component should also be set to an appropriate one more specific than <tt>New Bugs</tt> if necessary.</li>
38 </ul>
39
40 <h3>Analyzing Bugs</h3>
41
42 <p>Each bug is initially assigned to the person designated as owner of the component. The assignee should move the bug from status
43 <tt>NEW</tt> to status <tt>ASSIGNED</tt> after they have read the bug and are satisfied that it represents a real problem in WebKit.
44 If they are not satisfied about this, they should perform one of the actions mentioned in the <a href="#confirming">Confirming Bugs</a> section above.
45 The same procedure is followed for bugs with status <tt>REOPENED</tt> (see <a href="#verifying">Verifying Fixes</a> below).</p>
46
47 <p>The assignee represents the person who is expected to take the next step in investigating or fixing a bug. If someone other than the assignee is
48 investigating or fixing a bug, the assignee should be changed to the person doing the work. This helps prevent duplicated work. It's always helpful to add 
49 a comment explaining why an assignee has been changed.</p>
50
51 <h3>Proposing Fixes</h3>
52
53 <p>A proposed patch should be added as a new attachment. The attachment should have the <tt>patch</tt> checkbox checked, and the <tt>review</tt> flag set to <tt>?</tt>. This
54 marks the patch as awaiting review. If the patch requires the specialized knowledge of a particular reviewer, the submitter or another reviewer should put
55 the requested reviewer's email address in the <tt>Requestee</tt> field. Otherwise this field should be left empty. The state is left at <tt>ASSIGNED</tt> at
56 this point; it isn't changed to <tt>FIXED</tt> until a fix has been checked into the source tree.</p>
57
58 <p>When the review flag's state is changed, or when a comment is made in the Edit form for an attachment, email is automatically sent to
59 the <a href="http://www.opendarwin.org/mailman/listinfo/webkit-reviews">webkit-reviews</a> mailing list. The reviewers all subscribe to
60 this list, and anyone else is free to do so as well.</p>
61
62 <p>If the submitter of a patch changes their mind about wanting a review, they should clear the <tt>review</tt> flag by choosing the
63 blank choice in the review pop-menu.</p>
64
65 <p>More details about how to prepare code changes can be found <a href="../coding/contributing.html">elsewhere on this site</a>.</p>
66
67 <h3>Reviewing Proposed Fixes</h3>
68
69 <p>A reviewer will read through each proposed patch. If the patch is ready to commit, the reviewer will change the <tt>review</tt> flag to <tt>+</tt>. 
70 For clarity, it's helpful for the reviewer to add a comment when approving a patch. Often this comment is just "r=me", which is simply shorthand for 
71 "I have reviewed this patch and it's ready to commit".</p>
72
73 <p>A patch might not be ready to commit for various reasons. The bug fix might be incorrect. The <a href="testwriting.html">test cases</a> included in the patch might be insufficient.
74 The bug fix and test cases might be fine but the <a href="../coding/coding-style.html">coding style</a> might be incorrect. The reviewer should always 
75 explain in detail why a patch is not ready to commit, so the submitter or someone else can revise the patch.</p>
76
77 <p>When a submitter proposes an updated patch, they should check the <tt>obsolete</tt> checkbox on the previous version of the patch. This causes it
78 to appear crossed-out in the list of attachments on the bug's main page. At the same time as marking the old patch <tt>obsolete</tt>, the 
79 submitter should also clear the <tt>review</tt> flag. This would happen automatically in a perfect world, but doesn't currently in this one.</p>
80
81 <h3>Committing Patches</h3>
82
83 <p>After a patch has been approved, someone with commit privileges in the WebKit source repository will commit the patch into the source code repository. The committer
84 should change the state of the bug to <tt>FIXED</tt>; generally the assignee is left unchanged at this point.</p>
85
86 <p>All of the
87 people with commit privileges should be subscribed to the <a href="http://www.opendarwin.org/mailman/listinfo/webkit-reviews">webkit-reviews</a>
88 mailing list, and so they will receive email when a patch is approved and thus ready to be committed. If an approved patch has not been committed for what seems to be an inordinately
89 long time, the patch submitter could send email requesting status to this mailing list. As a last resort, the patch submitter could contact the
90 reviewer directly. Due to everyone's busy schedules, some delays in getting patches reviewed, and then in getting them committed, are inevitable.</p>
91
92 <p>If the bug report mentions that the same bug is represented in Apple's internal Radar system, and the person who commits the bug has acces to Radar, then the 
93 person who commits the bug should also set the state of the Radar bug to Software Changed/Integrate.</p>
94
95 <h3><a name="verifying"></a>Verifying Fixes</h3>
96
97 <p>After the patch for a bug has been committed, the fix still needs to be verified. Typically this step is done by the person who originally submitted the 
98 bug report. If the submitter is not available or does not feel that they can verify the fix, the verification step can be done by anyone with bug editing 
99 privileges who is familiar enough with the originally reported problem to be confident about
100 testing it. Note that once a bug is in the <tt>FIXED</tt> state, the assignee can no longer be changed. This means that a bug that needs
101 to be verified will not usually be assigned to the person expected to verify the bug.</p>
102
103 <p>To verify a bug fix, build and run the sources that include the fix, and check whether
104 the originally reported problem still occurs. If the problem no longer occurs, change the resolution to <tt>VERIFIED</tt>. If the problem does still occur,
105 change the resolution to <tt>REOPENED</tt> and assign it to the person who submitted the patch.</p>
106
107
108 <h3>Closing Bugs</h3>
109
110 <p>Fixed bugs have the <tt>VERIFIED</tt> resolution until a version of WebKit that includes the fix has been publicly released. At this point,
111 the resolution is changed to <tt>CLOSED</tt>.
112
113 <?php
114         include("../footer.inc");
115 ?>