1=================== 2LLVM Bug Life Cycle 3=================== 4 5.. contents:: 6 :local: 7 8 9 10Introduction - Achieving consistency in how we deal with bug reports 11==================================================================== 12 13We aim to achieve a basic level of consistency in how reported bugs evolve from 14being reported, to being worked on, and finally getting closed out. The 15consistency helps reporters, developers and others to gain a better 16understanding of what a particular bug state actually means and what to expect 17might happen next. 18 19At 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>`_, 21as the overall goal is to make it easier to work with and understand the bug 22reports. 23 24The main parts of the life cycle documented here are: 25 26#. `Reporting`_ 27#. `Triaging`_ 28#. `Actively working on fixing`_ 29#. `Closing`_ 30 31Furthermore, some of the metadata in the bug tracker, such as what labels we 32use, needs to be maintained. See the following for details: 33 34#. `Maintenance of metadata`_ 35 36 37.. _Reporting: 38 39Reporting bugs 40============== 41 42See :doc:`HowToSubmitABug` on further details on how to submit good bug reports. 43 44You can apply `labels <https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/managing-labels>`_ 45to the bug to provide extra information to make the bug easier to discover, such 46as a label for the part of the project the bug pertains to. 47 48.. _Triaging: 49 50Triaging bugs 51============= 52 53Open bugs that have not been marked with the ``confirmed`` label are bugs that 54still need to be triaged. When triage is complete, the ``confirmed`` label 55should be added along with any other labels that help to classify the report, 56unless the issue is being :ref:`closed<Closing>`. 57 58The goal of triaging a bug is to make sure a newly reported bug ends up in a 59good, 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 97Actively working on fixing bugs 98=============================== 99 100Please remember to assign the bug to yourself if you're actively working on 101fixing it and to unassign it when you're no longer actively working on it. You 102unassign a bug by removing the person from the ``Assignees`` field. 103 104.. _Closing: 105 106Resolving/Closing bugs 107====================== 108 109Resolving bugs is good! Make sure to properly record the reason for resolving. 110Examples 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 140Maintenance of metadata 141======================= 142 143Project member with write access to the project can create new labels, but we 144discourage adding ad hoc labels because we want to control the proliferation of 145labels and avoid single-use labels. If you would like a new label added, please 146open an issue asking to create an issue label and add the ``infrastructure`` 147label to the issue. The request should include a description of what the label 148is for. Alternatively, you can ask for the label to be created on the 149``#infrastructure`` channel on the LLVM Discord. 150