llvm.org GIT mirror llvm / 1f633af
Introduce bug life cycle documentation. Document what is expected during: * triaging * actively working on a bug * closing/resolving Also document how we maintain: * product/component breakdown * default-cc lists per component Differential Revision: https://reviews.llvm.org/D53691 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@346299 91177308-0d34-0410-b5e6-96231b3b80d8 Kristof Beyls 11 months ago
3 changed file(s) with 150 addition(s) and 0 deletion(s). Raw diff Collapse all Expand all
0 ===================
1 LLVM Bug Life Cycle
2 ===================
3
4 .. contents::
5 :local:
6
7
8
9 Introduction - Achieving consistency in how we deal with bug reports
10 ====================================================================
11
12 We aim to achieve a basic level of consistency in how reported bugs evolve from
13 being reported, to being worked on, and finally getting closed out. The
14 consistency helps reporters, developers and others to gain a better
15 understanding of what a particular bug state actually means and what to expect
16 might happen next.
17
18 At the same time, we aim to not over-specify the life cycle of bugs in the
19 `the LLVM Bug Tracking System `_, as the
20 overall goal is to make it easier to work with and understand the bug reports.
21
22 The main parts of the life cycle documented here are:
23
24 #. `Reporting`_
25 #. `Triaging`_
26 #. `Actively working on fixing`_
27 #. `Closing`_
28
29 Furthermore, some of the metadata in the bug tracker, such as who to notify on
30 newly reported bugs or what the breakdown into products & components is we use,
31 needs to be maintained. See the following for details:
32
33 #. `Maintenance of Bug products/component metadata`_
34 #. `Maintenance of cc-by-default settings`_
35
36
37 .. _Reporting:
38
39 Reporting bugs
40 ==============
41
42 See :doc:`HowToSubmitABug` on further details on how to submit good bug reports.
43
44 Make sure that you have one or more people on cc on the bug report that you
45 think will react to it. We aim to automatically add specific people on cc for
46 most products/components, but may not always succeed in doing so.
47
48 If you know the area of LLVM code the root cause of the bug is in, good
49 candidates to add as cc may be the same people you'd ask for a code review in
50 that area. See :ref:`finding-potential-reviewers` for more details.
51
52
53 .. _Triaging:
54
55 Triaging bugs
56 =============
57
58 Bugs with status NEW indicate that they still need to be triaged.
59 When triage is complete, the status of the bug is moved to CONFIRMED.
60
61 The goal of triaging a bug is to make sure a newly reported bug ends up in a
62 good, actionable, state. Try to answer the following questions while triaging.
63
64 * Is the reported behavior actually wrong?
65
66 * E.g. does a miscompile example depend on undefined behavior?
67
68 * Can you easily reproduce the bug?
69
70 * If not, are there reasonable excuses why it cannot easily be reproduced?
71
72 * Is it related to an already reported bug?
73
74 * Use the "See also"/"depends on"/"blocks" fields if so.
75 * Close it as a duplicate if so, pointing to the issue it duplicates.
76
77 * Are the following fields filled in correctly?
78
79 * Product
80 * Component
81 * Title
82
83 * CC others not already cc’ed that you happen to know would be good to pull in.
84 * Add the "beginner" keyword if you think this would be a good bug to be fixed
85 by someone new to LLVM.
86
87 .. _Actively working on fixing:
88
89 Actively working on fixing bugs
90 ===============================
91
92 Please remember to assign the bug to yourself if you're actively working on
93 fixing it and to unassign it when you're no longer actively working on it. You
94 unassign a bug by setting the Assignee field to "unassignedbugs@nondot.org".
95
96 .. _Closing:
97
98 Resolving/Closing bugs
99 ======================
100
101 For simplicity, we only have 1 status for all resolved or closed bugs:
102 RESOLVED.
103
104 Resolving bugs is good! Make sure to properly record the reason for resolving.
105 Examples of reasons for resolving are:
106
107 * Revision NNNNNN fixed the bug.
108 * The bug cannot be reproduced with revision NNNNNN.
109 * The circumstances for the bug don't apply anymore.
110 * There is a sound reason for not fixing it (WONTFIX).
111 * There is a specific and plausible reason to think that a given bug is
112 otherwise inapplicable or obsolete.
113
114 * One example is an old open bug that doesn't contain enough information to
115 clearly understand the problem being reported (e.g. not reproducible). It is
116 fine to resolve such a bug e.g. with resolution WORKSFORME and leaving a
117 comment to encourage the reporter to reopen the bug with more information
118 if it's still reproducable on their end.
119
120 If a bug is resolved, please fill in the revision number it was fixed in in the
121 "Fixed by Commit(s)" field.
122
123
124 .. _Maintenance of Bug products/component metadata:
125
126 Maintenance of products/components metadata
127 ===========================================
128
129 Please raise a bug against "Bugzilla Admin"/"Products" to request any changes
130 to be made to the breakdown of products & components modeled in Bugzilla.
131
132
133 .. _Maintenance of cc-by-default settings:
134
135 Maintenance of cc-by-default settings
136 =====================================
137
138 Please raise a bug against "Bugzilla Admin"/"Products" to request any changes
139 to be made to the cc-by-default settings for specific components.
9393 or llvm-commits, and if the subject line suggests the patch is something they
9494 should look at, they will.
9595
96
97 .. _finding-potential-reviewers:
98
99 Finding potential reviewers
100 ---------------------------
101
96102 Here are a couple of ways to pick the initial reviewer(s):
97103
98104 * Use ``svn blame`` and the commit log to find names of people who have
453453 Packaging
454454 ReleaseProcess
455455 Phabricator
456 BugLifeCycle
456457
457458 :doc:`Contributing`
458459 An overview on how to contribute to LLVM.
482483 :doc:`Phabricator`
483484 Describes how to use the Phabricator code review tool hosted on
484485 http://reviews.llvm.org/ and its command line interface, Arcanist.
486
487 :doc:`BugLifeCycle`
488 Describes how bugs are reported, triaged and closed.
485489
486490 Community
487491 =========