From 2fe686afa0497ac10a2cee87d25ff5c31fb5188b Mon Sep 17 00:00:00 2001 From: Kristof Beyls Date: Wed, 7 Nov 2018 08:49:36 +0000 Subject: [PATCH] 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 llvm-svn: 346299 --- docs/BugLifeCycle.rst | 140 ++++++++++++++++++++++++++++++++++++++++++ docs/Phabricator.rst | 6 ++ docs/index.rst | 4 ++ 3 files changed, 150 insertions(+) create mode 100644 docs/BugLifeCycle.rst diff --git a/docs/BugLifeCycle.rst b/docs/BugLifeCycle.rst new file mode 100644 index 00000000000..c74aa1d3a62 --- /dev/null +++ b/docs/BugLifeCycle.rst @@ -0,0 +1,140 @@ +=================== +LLVM Bug Life Cycle +=================== + +.. contents:: + :local: + + + +Introduction - Achieving consistency in how we deal with bug reports +==================================================================== + +We aim to achieve a basic level of consistency in how reported bugs evolve from +being reported, to being worked on, and finally getting closed out. The +consistency helps reporters, developers and others to gain a better +understanding of what a particular bug state actually means and what to expect +might happen next. + +At the same time, we aim to not over-specify the life cycle of bugs in the +`the LLVM Bug Tracking System `_, as the +overall goal is to make it easier to work with and understand the bug reports. + +The main parts of the life cycle documented here are: + +#. `Reporting`_ +#. `Triaging`_ +#. `Actively working on fixing`_ +#. `Closing`_ + +Furthermore, some of the metadata in the bug tracker, such as who to notify on +newly reported bugs or what the breakdown into products & components is we use, +needs to be maintained. See the following for details: + +#. `Maintenance of Bug products/component metadata`_ +#. `Maintenance of cc-by-default settings`_ + + +.. _Reporting: + +Reporting bugs +============== + +See :doc:`HowToSubmitABug` on further details on how to submit good bug reports. + +Make sure that you have one or more people on cc on the bug report that you +think will react to it. We aim to automatically add specific people on cc for +most products/components, but may not always succeed in doing so. + +If you know the area of LLVM code the root cause of the bug is in, good +candidates to add as cc may be the same people you'd ask for a code review in +that area. See :ref:`finding-potential-reviewers` for more details. + + +.. _Triaging: + +Triaging bugs +============= + +Bugs with status NEW indicate that they still need to be triaged. +When triage is complete, the status of the bug is moved to CONFIRMED. + +The goal of triaging a bug is to make sure a newly reported bug ends up in a +good, actionable, state. Try to answer the following questions while triaging. + +* Is the reported behavior actually wrong? + + * E.g. does a miscompile example depend on undefined behavior? + +* Can you easily reproduce the bug? + + * If not, are there reasonable excuses why it cannot easily be reproduced? + +* Is it related to an already reported bug? + + * Use the "See also"/"depends on"/"blocks" fields if so. + * Close it as a duplicate if so, pointing to the issue it duplicates. + +* Are the following fields filled in correctly? + + * Product + * Component + * Title + +* CC others not already cc’ed that you happen to know would be good to pull in. +* Add the "beginner" keyword if you think this would be a good bug to be fixed + by someone new to LLVM. + +.. _Actively working on fixing: + +Actively working on fixing bugs +=============================== + +Please remember to assign the bug to yourself if you're actively working on +fixing it and to unassign it when you're no longer actively working on it. You +unassign a bug by setting the Assignee field to "unassignedbugs@nondot.org". + +.. _Closing: + +Resolving/Closing bugs +====================== + +For simplicity, we only have 1 status for all resolved or closed bugs: +RESOLVED. + +Resolving bugs is good! Make sure to properly record the reason for resolving. +Examples of reasons for resolving are: + +* Revision NNNNNN fixed the bug. +* The bug cannot be reproduced with revision NNNNNN. +* The circumstances for the bug don't apply anymore. +* There is a sound reason for not fixing it (WONTFIX). +* There is a specific and plausible reason to think that a given bug is + otherwise inapplicable or obsolete. + + * One example is an old open bug that doesn't contain enough information to + clearly understand the problem being reported (e.g. not reproducible). It is + fine to resolve such a bug e.g. with resolution WORKSFORME and leaving a + comment to encourage the reporter to reopen the bug with more information + if it's still reproducable on their end. + +If a bug is resolved, please fill in the revision number it was fixed in in the +"Fixed by Commit(s)" field. + + +.. _Maintenance of Bug products/component metadata: + +Maintenance of products/components metadata +=========================================== + +Please raise a bug against "Bugzilla Admin"/"Products" to request any changes +to be made to the breakdown of products & components modeled in Bugzilla. + + +.. _Maintenance of cc-by-default settings: + +Maintenance of cc-by-default settings +===================================== + +Please raise a bug against "Bugzilla Admin"/"Products" to request any changes +to be made to the cc-by-default settings for specific components. diff --git a/docs/Phabricator.rst b/docs/Phabricator.rst index 53cb3b5980a..640e1611da6 100644 --- a/docs/Phabricator.rst +++ b/docs/Phabricator.rst @@ -94,6 +94,12 @@ them to participate. Many people will see the email notification on cfe-commits or llvm-commits, and if the subject line suggests the patch is something they should look at, they will. + +.. _finding-potential-reviewers: + +Finding potential reviewers +--------------------------- + Here are a couple of ways to pick the initial reviewer(s): * Use ``svn blame`` and the commit log to find names of people who have diff --git a/docs/index.rst b/docs/index.rst index de9218e6f4c..df70de095bd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -454,6 +454,7 @@ Information about LLVM's development process. Packaging ReleaseProcess Phabricator + BugLifeCycle :doc:`Contributing` An overview on how to contribute to LLVM. @@ -484,6 +485,9 @@ Information about LLVM's development process. Describes how to use the Phabricator code review tool hosted on http://reviews.llvm.org/ and its command line interface, Arcanist. +:doc:`BugLifeCycle` + Describes how bugs are reported, triaged and closed. + Community =========