From cb68c39f651c478ccdba569eb5076acc02ca32f8 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 23 May 2021 21:57:50 -0700 Subject: [PATCH] Expound on issue tracking guidelines --- introduction/reporting-bugs.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/introduction/reporting-bugs.md b/introduction/reporting-bugs.md index cd75bb6e..088e4104 100644 --- a/introduction/reporting-bugs.md +++ b/introduction/reporting-bugs.md @@ -49,6 +49,12 @@ It is not a place for discussion. If you wish to discuss something in the issue tracker, please do so on the forum or mailing lists (see [Help, Support, Mailing Lists, and Forum](/support/)). You can simply link to the relevant issue in your discussion post. +This guideline is important for keeping issues focused on *actionable information*, which helps the develpers to stay focused on their work. +When developers come back to an issue to work on it, we do not want them to have to sift through a large number of unnecessary comments before they can get started. +In many cases, an issue that gets "too big" essentially becomes more trouble than it's worth, and no developer will touch it (also see [every issue must be about a single, actionable thing](#every-issue-must-be-about-a-single-actionable-thing)). +In these cases, we sometimes have to close the issue and open a new one. +This is a waste of energy for everyone involved, so we ask that everyone help to avoid repeating this pattern. + ### Do not submit questions ### [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is not the place to ask questions. @@ -60,6 +66,12 @@ By contrast, [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is m If your issue is not actionable, please see [Help, Support, Mailing Lists, and Forum](/support/) for the appropriate place to post it. If your issue would be about more than one thing, file them as separate issues instead. +This means we should generally not try to use a single issue as a "meta" or "epic" issue that exists only to group, contain, or track other issues. +Instead, when there is a need to group multiple related issues together, use [projects](https://github.com/QubesOS/qubes-issues/projects). + +This guideline is extremely important for making the issue tracker a useful tool for the developers. +When an issue is too big and composite, it becomes intractable and drastically increases the likelihood that nothing will get done. +Such issues also tend to encourage an excessive amount of general discussion that is simply not appropriate for a technical issue tracker (see [the issue tracker is not a discussion forum](#the-issue-tracker-is-not-a-discussion-forum)). ### New issues should not be duplicates of existing issues ###