llvm/docs/BugLifeCycle.rst

   1 ===================
   2 LLVM Bug Life Cycle
   3 ===================
   4
   5 .. contents::
   6    :local:
   7
   8
   9
  10 Introduction - Achieving consistency in how we deal with bug reports
  11 ====================================================================
  12
  13 We aim to achieve a basic level of consistency in how reported bugs evolve from
  14 being reported, to being worked on, and finally getting closed out. The
  15 consistency helps reporters, developers and others to gain a better
  16 understanding of what a particular bug state actually means and what to expect
  17 might happen next.
  18
  19 At the same time, we aim to not over-specify the life cycle of bugs in
  20 `the LLVM Bug Tracking System <https://github.com/llvm/llvm-project/issues>`_,
  21 as the overall goal is to make it easier to work with and understand the bug
  22 reports.
  23
  24 The main parts of the life cycle documented here are:
  25
  26 #. `Reporting`_
  27 #. `Triaging`_
  28 #. `Actively working on fixing`_
  29 #. `Closing`_
  30
  31 Furthermore, some of the metadata in the bug tracker, such as what labels we
  32 use, needs to be maintained. See the following for details:
  33
  34 #. `Maintenance of metadata`_
  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 You can apply `labels <https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/managing-labels>`_
  45 to the bug to provide extra information to make the bug easier to discover, such
  46 as a label for the part of the project the bug pertains to.
  47
  48 .. _Triaging:
  49
  50 Triaging bugs
  51 =============
  52
  53 Open bugs that have not been marked with the ``confirmed`` label are bugs that
  54 still need to be triaged. When triage is complete, the ``confirmed`` label
  55 should be added along with any other labels that help to classify the report,
  56 unless the issue is being :ref:`closed<Closing>`.
  57
  58 The goal of triaging a bug is to make sure a newly reported bug ends up in a
  59 good, actionable state. Try to answer the following questions while triaging:
  60
  61 * Is the reported behavior actually wrong?
  62
  63   * E.g. does a miscompile example depend on undefined behavior?
  64
  65 * Can you reproduce the bug from the details in the report?
  66
  67   * If not, is there a reasonable explanation why it cannot be reproduced?
  68
  69 * Is it related to an already reported bug?
  70
  71 * Are the following fields filled in correctly?
  72
  73   * Title
  74   * Description
  75   * Labels
  76
  77 * When able to do so, please add the appropriate labels to classify the bug,
  78   such as the tool (``clang``, ``clang-format``, ``clang-tidy``, etc) or
  79   component (``backend:<name>``, ``compiler-rt:<name>``, ``clang:<name>``, etc).
  80
  81 * If the issue is with a particular revision of the C or C++ standard, please
  82   add the appropriate language standard label (``c++20``, ``c99``, etc).
  83
  84 * Please don't use both a general and a specific label. For example, bugs
  85   labeled ``c++17`` shouldn't also have ``c++``, and bugs labeled
  86   ``clang:codegen`` shouldn't also have ``clang``.
  87
  88 * Add the ``good first issue`` label if you think this would be a good bug to
  89   be fixed by someone new to LLVM. This label feeds into `the landing page
  90   for new contributors <https://github.com/llvm/llvm-project/contribute>`_.
  91
  92 * If you are unsure of what a label is intended to be used for, please see the
  93   `documentation for our labels <https://github.com/llvm/llvm-project/labels>`_.
  94
  95 .. _Actively working on fixing:
  96
  97 Actively working on fixing bugs
  98 ===============================
  99
 100 Please remember to assign the bug to yourself if you're actively working on
 101 fixing it and to unassign it when you're no longer actively working on it.  You
 102 unassign a bug by removing the person from the ``Assignees`` field.
 103
 104 .. _Closing:
 105
 106 Resolving/Closing bugs
 107 ======================
 108
 109 Resolving bugs is good! Make sure to properly record the reason for resolving.
 110 Examples of reasons for resolving are:
 111
 112   * If the issue has been resolved by a particular commit, close the issue with
 113     a brief comment mentioning which commit(s) fixed it. If you are authoring
 114     the fix yourself, your git commit message may include the phrase
 115     ``Fixes #<issue number>`` on a line by itself. GitHub recognizes such commit
 116     messages and will automatically close the specified issue with a reference
 117     to your commit.
 118
 119   * If the reported behavior is not a bug, it is appropriate to close the issue
 120     with a comment explaining why you believe it is not a bug, and adding the
 121     ``invalid`` tag.
 122
 123   * If the bug duplicates another issue, close it as a duplicate by adding the
 124     ``duplicate`` label with a comment pointing to the issue it duplicates.
 125
 126   * If there is a sound reason for not fixing the issue (difficulty, ABI, open
 127     research questions, etc), add the ``wontfix`` label and a comment explaining
 128     why no changes are expected.
 129
 130   * If there is a specific and plausible reason to think that a given bug is
 131     otherwise inapplicable or obsolete. One example is an open bug that doesn't
 132     contain enough information to clearly understand the problem being reported
 133     (e.g. not reproducible). It is fine to close such a bug, adding with the
 134     ``worksforme`` label and leaving a comment to encourage the reporter to
 135     reopen the bug with more information if it's still reproducible for them.
 136
 137
 138 .. _Maintenance of metadata:
 139
 140 Maintenance of metadata
 141 =======================
 142
 143 Project member with write access to the project can create new labels, but we
 144 discourage adding ad hoc labels because we want to control the proliferation of
 145 labels and avoid single-use labels. If you would like a new label added, please
 146 open an issue asking to create an issue label and add the ``infrastructure``
 147 label to the issue. The request should include a description of what the label
 148 is for. Alternatively, you can ask for the label to be created on the
 149 ``#infrastructure`` channel on the LLVM Discord.