[PATCH] D117832: Update the Bug Life Cycle docs for the switch to GitHub issues

Thu Jan 20 14:10:10 PST 2022

Quuxplusone added a comment.

I've suggested several rewordings, or additional wordings; please take whatever seems good to you. I don't want to block this, regardless.

- Please use [good first issue] instead of [beginner].
- It is probably a good idea to list the four "resolution/disposition" labels explicitly somewhere as a foursome: [duplicate], [invalid], [wontfix], [worksforme]. Btw, do we think [obsolete] is also a resolution/disposition? I don't know what its intent was, but I think it's plausibly a sort of compromise between [invalid] and [wontfix], right? If that's our intent, then we should color-code [obsolete] as a resolution (color #cccccc) and mention it in the same breath with the other four.

================
Comment at: llvm/docs/BugLifeCycle.rst:54-56
+Bugs with a ``new issue`` label indicate that the issue stills need to be
+triaged. When triage is complete, the ``new issue`` label should be replaced by
+a ``confirmed`` label, unless the issue is being closed.
----------------
Any open bug without the [confirmed] label is a bug that still needs to be triaged. When triage is complete, if the bug isn't simply being closed, the bug should be labeled [confirmed].
The goal is that a bug marked [confirmed] is in a good, actionable state.

I would prefer not to mention the [new issue] label at all, here, since it isn't consistently applied to new issues and also isn't consistently removed from triaged issues. Also, we should strive to limit the amount of "process" involved here; "add this label" is 50% less process than "add this label and remove that label," especially when "that label" was merely added by a bot to begin with.
https://github.com/llvm/llvm-project/issues?q=label%3A%22new+issue%22

Reductio ad absurdam: We could change the "new issue" bot so that it also //removes// the [new issue] label from any bug that already possesses the [confirmed] tag, and/or from any bug that is closed. (Right now there are 42 closed bugs with the [new issue] tag.) We could also change the bot to //add// the [new issue] tag to any bug that is open but lacks [confirmed]. Basically we can let the bot run free with that label, and leave the humans to ignore it. :)

================
Comment at: llvm/docs/BugLifeCycle.rst:63

   * E.g. does a miscompile example depend on undefined behavior?

----------------
If the reported behavior is not a bug, it is appropriate to close the issue with the label [invalid], and a comment explaining why you believe it's not a bug.

================
Comment at: llvm/docs/BugLifeCycle.rst:67

   * If not, are there reasonable excuses why it cannot easily be reproduced?

----------------
If the bug really can't be reproduced, it might be appropriate to close it with the label [worksforme], and a comment explaining your rationale. But this closure reason should be used very sparingly and judiciously, and probably only if the original submitter is no longer responding.

================
Comment at: llvm/docs/BugLifeCycle.rst:71-72

-  * Use the "See also"/"depends on"/"blocks" fields if so.
-  * Close it as a duplicate if so, pointing to the issue it duplicates.
+  * Close it as a duplicate by adding the label ``duplicate`` if so, with a
+    comment pointing to the issue it duplicates.

----------------
The fourth "resolution" label is [wontfix], which we use for things that are arguably deficiencies or bugs, but which for one reason or another (difficulty, ABI, open research questions) we know aren't going to be changed and further discussion is really, truly pointless.
...Ah, I see you cover this in "Resolving/Closing Bugs" below. Consider adding a hyperlink to "Resolving/Closing Bugs" in the bullet points above that talk about essentially [invalid] and [worksforme] (as opposed to adopting my comment-suggested-wording).

================
Comment at: llvm/docs/BugLifeCycle.rst:80

-* 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
+* Add the ``beginner`` label if you think this would be a good bug to be fixed
   by someone new to LLVM.
----------------
As Tom says, please use [good first issue] here instead. It is meaningful to GitHub: it populates https://github.com/llvm/llvm-project/contribute and several third-party websites aimed at new FOSS contributors.

[beginner], by contrast, came from a Bugzilla keyword during the migration. I don't know for sure what its original intent was, but I agree it seems like a synonym for [good first issue]. (And therefore I suggest we retag all 89 open [beginner] issues as [good first issue] and then burninate the [beginner] tag. But I won't do that unless someone tells me to. ;))

================
Comment at: llvm/docs/BugLifeCycle.rst:109
     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
+    fine to resolve such a bug e.g. with the ``worksforme`` label and leaving a
     comment to encourage the reporter to reopen the bug with more information
----------------

================
Comment at: llvm/docs/BugLifeCycle.rst:113-114

-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.
+If a bug is resolved, please add the revision number it was fixed in as a
+comment when closing the issue.

----------------
When an issue is fixed, please add a brief comment when you close the issue, pointing to the commit that fixed it. For example: "Fixed in 1b2c3d4."

If you are authoring the fix yourself, then your git commit message may include the phrase "Fixes #54321" on a line by itself. GitHub recognizes such commit messages and will automatically close the issue with a pointer to your commit, so that you don't have to.

================
Comment at: llvm/docs/BugLifeCycle.rst:122-125
+Please add the ``infrastructure`` label to request any changes to be made to
+the labels used by the issue tracker instead of creating your own label. This
+increases consistency when triaging and helps reduce the proliferation of
+labels.
----------------
I think this is saying: Any project member can create new labels, but we discourage it, because we don't want a proliferation of similar or single-use labels. If you are not a project member — or even if you are! — then when you want a new label created, please open a GitHub issue with the subject line "Create issue label [foo]", add the [infrastructure] label to that issue itself, and wait. (For what, exactly?)

My impression is that a better/faster alternative is to speak up in the #infrastructure channel on the Discord.

Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D117832/new/

https://reviews.llvm.org/D117832