[llvm] r346299 - Introduce bug life cycle documentation.

Wed Nov 7 00:49:36 PST 2018

Author: kbeyls
Date: Wed Nov  7 00:49:36 2018
New Revision: 346299

URL: http://llvm.org/viewvc/llvm-project?rev=346299&view=rev
Log:
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

Added:
    llvm/trunk/docs/BugLifeCycle.rst
Modified:
    llvm/trunk/docs/Phabricator.rst
    llvm/trunk/docs/index.rst

Added: llvm/trunk/docs/BugLifeCycle.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/BugLifeCycle.rst?rev=346299&view=auto
==============================================================================

--- llvm/trunk/docs/BugLifeCycle.rst (added)
+++ llvm/trunk/docs/BugLifeCycle.rst Wed Nov  7 00:49:36 2018
@@ -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 <https://bugs.llvm.org/enter_bug.cgi>`_, 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 at 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.

Modified: llvm/trunk/docs/Phabricator.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/Phabricator.rst?rev=346299&r1=346298&r2=346299&view=diff
==============================================================================
--- llvm/trunk/docs/Phabricator.rst (original)
+++ llvm/trunk/docs/Phabricator.rst Wed Nov  7 00:49:36 2018
@@ -94,6 +94,12 @@ them to participate. Many people will se
 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

Modified: llvm/trunk/docs/index.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/index.rst?rev=346299&r1=346298&r2=346299&view=diff
==============================================================================
--- llvm/trunk/docs/index.rst (original)
+++ llvm/trunk/docs/index.rst Wed Nov  7 00:49:36 2018
@@ -454,6 +454,7 @@ Information about LLVM's development pro
    Packaging
    ReleaseProcess
    Phabricator
+   BugLifeCycle
 
 :doc:`Contributing`
    An overview on how to contribute to LLVM.
@@ -484,6 +485,9 @@ Information about LLVM's development pro
    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
 =========
 


