From e50aa57291cf7f92ac98d9ce2ac9566f3fe69f9c Mon Sep 17 00:00:00 2001
From: jack1142 <6032823+jack1142@users.noreply.github.com>
Date: Sun, 11 Jul 2021 03:04:39 +0200
Subject: [PATCH 1/6] Document life cycle of an issue
---
source/images/triaging.drawio | 357 ++++++++++++++++++++++++++++++++++
source/images/triaging.svg | 3 +
source/index.rst | 2 +
source/triaging-issues.rst | 64 ++++++
4 files changed, 426 insertions(+)
create mode 100644 source/images/triaging.drawio
create mode 100644 source/images/triaging.svg
create mode 100644 source/triaging-issues.rst
diff --git a/source/images/triaging.drawio b/source/images/triaging.drawio
new file mode 100644
index 0000000..f48d32f
--- /dev/null
+++ b/source/images/triaging.drawio
@@ -0,0 +1,357 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/source/images/triaging.svg b/source/images/triaging.svg
new file mode 100644
index 0000000..92d704c
--- /dev/null
+++ b/source/images/triaging.svg
@@ -0,0 +1,3 @@
+
+
+
diff --git a/source/index.rst b/source/index.rst
index 759f538..7871f9a 100644
--- a/source/index.rst
+++ b/source/index.rst
@@ -9,3 +9,5 @@ Full Table of Contents
.. toctree::
:maxdepth: 2
+
+ triaging-issues
diff --git a/source/triaging-issues.rst b/source/triaging-issues.rst
new file mode 100644
index 0000000..19ba3d8
--- /dev/null
+++ b/source/triaging-issues.rst
@@ -0,0 +1,64 @@
+Triaging issues
+===============
+
+Red is quite a big project with many issues to keep track of and therefore it is important to
+properly organize them, and minimize the time needed to work with and on them.
+
+Life cycle of an issue
+----------------------
+
+.. figure:: images/triaging.svg
+
+#. The issue is waiting for triage (**Status: Needs Triage**)
+#. The issue has been tagged with category, type and other relevant labels
+ (**Status: Awaiting For Needs**)
+
+ - If there is not enough information to go on, appropriate **Needs** labels have been applied.
+ - If triager asked the author for more information, **Needs: Author Feedback** label has been
+ applied.
+
+ - If the author responds, automation will replace this label with **Needs: Attention**
+ to signify that triager needs to get back to this issue.
+ - If the author doesn't respond, the issue will be automatically closed after 7 days.
+
+#. The issue has been identified
+
+ - If the issue is not actionable (duplicate, external, no reproduction, etc.),
+ it has been closed and applied an appropriate **Resolution** label.
+ - If this is an issue that does not require a design (especially bugs, but also documentation
+ issues and *possibly* some enhancements), **Status: Accepted - PRs welcome** label has been
+ applied.
+ - If this is anything else (i.e. this is a feature or enhancement request),
+ **Needs: Decision** label has been applied.
+
+ - This is the moment where the issue has to wait for voting org member(s) to decide
+ whether this issue should be pursued.
+
+#. The issue has been evaluated by a voting org member (**Status: Accepted - \***)
+
+ - If the decision is that the issue should not be pursued, the issue has been closed with
+ the **Resolution: Won't Fix** label.
+ - If the decision is that the issue should be pursued...
+
+ - ...but it needs more discussion about the details of its implementation,
+ the issue has been marked with **Status: Accepted - Needs Design** label.
+ - ...and can be worked on right ahead, the issue has been marked with
+ **Status: Accepted - PRs Welcome** label.
+
+#. A contributor or org member wants to work on the issue
+
+ - If it is an org member, **Status: In Progress** label has been applied.
+ - If it is a contributor, the issue remains with its current status until PR is made.
+
+#. A PR addressing the issue has been made (**Status: PR Available**)
+
+ The automation automatically updates the labels if the issue was marked with
+ **Status: Accepted - PRs Welcome** or **Status: In Progress** label.
+
+ - If PR gets closed (not merged), the issue goes back to its previous **Status**.
+ - If PR gets merged, the issue gets automatically closed by GitHub.
+ and automation applies **Status: Resolved** and **Resolution: Fix Committed** label.
+
+#. A release with the fix has been made (**Status: Resolved**)
+
+ Automation applies **Resolution: Fix Released** label.
From 44d818da3d5004e320cc0131b1efe821c9d81be0 Mon Sep 17 00:00:00 2001
From: jack1142 <6032823+jack1142@users.noreply.github.com>
Date: Mon, 12 Jul 2021 02:03:10 +0200
Subject: [PATCH 2/6] Add description of fields in the issue tracker
---
source/triaging-issues.rst | 290 +++++++++++++++++++++++++++++++++++++
1 file changed, 290 insertions(+)
diff --git a/source/triaging-issues.rst b/source/triaging-issues.rst
index 19ba3d8..7f63a32 100644
--- a/source/triaging-issues.rst
+++ b/source/triaging-issues.rst
@@ -4,6 +4,8 @@ Triaging issues
Red is quite a big project with many issues to keep track of and therefore it is important to
properly organize them, and minimize the time needed to work with and on them.
+.. _life-cycle-of-an-issue:
+
Life cycle of an issue
----------------------
@@ -62,3 +64,291 @@ Life cycle of an issue
#. A release with the fix has been made (**Status: Resolved**)
Automation applies **Resolution: Fix Released** label.
+
+
+Fields in the Issue Tracker
+---------------------------
+
+All issues and PRs use a subset of these fields for categorization, indicating the state of
+the issue, and its progress toward resolution.
+
+.. tip::
+
+ The labels listed in this document might be marked with one of these:
+
+ .. [A] This label is applied by an automation.
+ .. [T] This label triggers an automation.
+
+Title
+~~~~~
+
+A brief description of the issue. Review whether the title is too generic or contains other text
+that would not be useful when filtering issues.
+
+Prefixes like ``[suggestion]``, ``[bank]``, ``[docs]`` are generally discouraged as they duplicate
+the information that is indicated by labels already.
+
+.. _Type:
+
+Type
+~~~~
+
+Describes the type of issue. Some issues might have multiple types, though it should be preferred
+to only label the issue with its main type(s).
+
+For example, a PR that adds a new functionality will most likely also update the documentation,
+but the PR should only be labeled with **Type: Feature** label.
+
+======================= ======================================================================
+Type Description
+======================= ======================================================================
+Bug Unexpected behavior, result, or exception.
+ In case of PRs, it is a fix for the foregoing.
+
+Dependency Update Adding/updating/removing some of Red's dependencies.
+
+Deprecation This intends to deprecate some functionality.
+
+Docs Improvements to the docs (e.g. new topic, correction, etc.).
+
+ Only used for issues and PRs that exclusively involve changes to
+ the documentation.
+
+Enhancement Something meant to enhance existing Red features.
+
+Feature New feature or request.
+
+Informational **(Issue-only)** Aims to provide information or facilitate discussion.
+
+Merge **(PR-only)** Merging changes between branches.
+
+Optimisation Situations where too much time is necessary to complete the task.
+
+Question This is a support question.
+
+ Issue should be closed as unactionable and author should be pointed
+ to Red's support server at https://discord.gg/red
+
+Removal This intends to remove some functionality.
+
+Tests Used for issues/PRs that exclusively involve changes to the tests.
+======================= ======================================================================
+
+.. _Category:
+
+Category
+~~~~~~~~
+
+Describes the area affected by the issue/PR. A single issue/PR can have multiple **Category**
+labels assigned.
+
+In case of Pull Requests, this is automatically applied and does not need to be touched by
+the triager.
+
+.. _Status:
+
+Status
+~~~~~~
+
+Describes the stage of resolution the issue is currently in.
+
+These are NOT used on Pull Requests.
+
+.. seealso::
+
+ `life-cycle-of-an-issue`
+
+================================ ==================================================================
+Status Description
+================================ ==================================================================
+Needs Triage [A]_ The issue needs to be triaged.
+ This involves labeling, asking the author for feedback,
+ reproducing bugs, etc.
+
+Awaiting For Needs Waiting for resolution of the `Needs` labels on this issue.
+
+Accepted - Needs Design The feature has been accepted but it needs voting org member(s) to
+ approve a design before PR for it can be worked on.
+
+Accepted - PRs Welcome The issue has been accepted and can be worked on.
+
+Accepted - In Progress An org member is working on this internally.
+
+Accepted - PR Available [A]_ This issue is accepted and has a related PR.
+
+ If the issue has not been accepted yet, this status is NOT used so
+ that the issues that still need a decision or triaging aren't
+ affected.
+
+ The label will be auto-applied *when* the label gets updated to
+ one of the labels it can transition from so this should never be
+ applied manually.
+
+Resolved [A]_ The issue has been resolved (closed).
+
+Frozen We are not currently interested in this but we might make plans
+ for it later.
+================================ ==================================================================
+
+.. _Needs:
+
+Needs
+~~~~~
+
+A needed next action to advance the issue.
+
+========================== ========================================================================
+Needs Description
+========================== ========================================================================
+Attention [A]_ The triager or reviewer needs to come back and look at this.
+
+ Auto-applied after the author responds to the issue that had a
+ `Status: Needs Author Feedback ` label.
+
+Author Feedback [T]_ The original author of the issue/PR needs to come back and respond to
+ something.
+
+ If this is an issue, it will be automatically commented on and labeled
+ with `No Activity ` label after 4 days of inactivity,
+ and closed after another 3 days of no activity.
+
+Community Feedback Indicates that we are interested in hearing more from our community
+ before continuing with this.
+
+Decision The voting org member(s) need to decide whether this issue should be
+ pursued.
+
+Label Fix [A]_ The issue doesn't match the label requirements (e.g. missing
+ `Type` or `Category` label).
+
+Repro We can't figure out how to make this happen.
+========================== ========================================================================
+
+.. _Blocked:
+
+Blocked
+~~~~~~~
+
+Indicates that the issue/PR is currently blocked by something.
+
+Blocked
+ A generic label indicating that the issue/PR is blocked for cases where none of the
+ **Blocked By** labels fit the reason for blocking.
+
+Blocked By: Damage Control
+ Blocked in the interest of preventing damage. Used when the PR could cause significant issues
+ if it were merged.
+
+Blocked By: Dependency
+ Blocked by a package listed as a dependency. Used when the issue/PR can't proceed
+ until some issue in one of our dependencies is fixed.
+
+Blocked By: Other PR
+ Blocked by another PR. Used when this issue/PR can't proceed until a different PR on the repo
+ is merged.
+
+.. _Release-Indicators:
+
+Release Indicators
+~~~~~~~~~~~~~~~~~~
+
+Labels that indicate something about when the issue/PR should/can be part of a release.
+
+Release Blocker
+ This needs handling prior to the next non-hotfix release.
+
+High Priority
+ This needs to be handled soon. Doesn't block a release, though it should still be considered.
+
+Breaking Change
+ Will cause breakage of some APIs. Can only be a part of ``3.x+1.0`` release.
+
+Needs Backport To 3.x
+ Needs to be backported to the 3.x version indicated by the label name.
+
+.. _Difficulty:
+
+Difficulty
+~~~~~~~~~~
+
+Indicates the difficulty of the issue to aid contributors in finding issues right for them.
+
+Complex Issue
+ This issue may require more than a surface level fix or be highly integrated with
+ other components.
+
+ These issues are not well-suited for people that aren't already familiar with the codebase.
+
+Good First Issue
+ This is a good issue for new contributors. Typically it is straightforward, well-defined,
+ low-risk, and optionally someone is able to mentor the new contributor.
+
+Help Wanted
+ We'd like help with this issue.
+
+.. _Keywords:
+
+Keywords
+~~~~~~~~
+
+Various informational flags about the issue/PR.
+
+QA: Bypassed
+ Review for this PR is unnecessary or needed to be bypassed.
+
+No Activity
+ This PR or issue hasn't had activity in a while.
+
+Automated PR
+ This PR has been automatically created GitHub Actions or integrations.
+
+Feature Branch [A]_
+ This PR is directed towards a feature branch, not ``V3/develop`` or ``3.x`` branches.
+
+QA: Changes Requested, QA: Passed
+ Few reviewers use these in their workflows, if you're not one of them you shouldn't use them.
+
+.. _Resolution:
+
+Resolution
+~~~~~~~~~~
+
+Describes why the issue was closed. Used for **all** closed issues and not actionable PRs.
+
+===================== ===========================================================================
+Resolution Description
+===================== ===========================================================================
+Duplicate There's another issue on the tracker that's pretty much the same thing.
+
+External For issues that are outside this codebase. Might be about
+ the lack of support from Discord.
+
+Fix Committed [A]_ The fix is checked in, but it has not been released yet.
+
+Fix Released [A]_ The fix has been released.
+
+No Repro We couldn't get this to happen, or it stopped happening entirely.
+
+Won't Fix It's supposed to be this way or we're not interested in fixing this.
+ There's probably a good reason.
+
+Not Actionable There is no action to be taken in response to this issue.
+===================== ===========================================================================
+
+.. _Changelog-Entry:
+
+Changelog Entry
+~~~~~~~~~~~~~~~
+
+Keeps track of changelog entry for the given PR. These are applied by the author of changelog as
+they're mostly meant to aid them with this task.
+
+==================== ==============================================================================
+Changelog Entry Description
+==================== ==============================================================================
+Pending [A]_ Changelog entry for this PR hasn't been added by changelog author yet.
+
+Skipped Changelog entry for this PR is unnecessary.
+
+Added Changelog entry for this PR has already been added to changelog PR.
+==================== ==============================================================================
From 5720b8bcd4cbfc9036faec4a7a45cc251e4ba72e Mon Sep 17 00:00:00 2001
From: jack1142 <6032823+jack1142@users.noreply.github.com>
Date: Sat, 17 Jul 2021 02:33:54 +0200
Subject: [PATCH 3/6] Rename images -> _images
---
source/{images => _images}/triaging.drawio | 0
source/{images => _images}/triaging.svg | 0
source/triaging-issues.rst | 2 +-
3 files changed, 1 insertion(+), 1 deletion(-)
rename source/{images => _images}/triaging.drawio (100%)
rename source/{images => _images}/triaging.svg (100%)
diff --git a/source/images/triaging.drawio b/source/_images/triaging.drawio
similarity index 100%
rename from source/images/triaging.drawio
rename to source/_images/triaging.drawio
diff --git a/source/images/triaging.svg b/source/_images/triaging.svg
similarity index 100%
rename from source/images/triaging.svg
rename to source/_images/triaging.svg
diff --git a/source/triaging-issues.rst b/source/triaging-issues.rst
index 7f63a32..a35ae5a 100644
--- a/source/triaging-issues.rst
+++ b/source/triaging-issues.rst
@@ -9,7 +9,7 @@ properly organize them, and minimize the time needed to work with and on them.
Life cycle of an issue
----------------------
-.. figure:: images/triaging.svg
+.. figure:: /_images/triaging.svg
#. The issue is waiting for triage (**Status: Needs Triage**)
#. The issue has been tagged with category, type and other relevant labels
From f534b0bc75d1957719b18a1c65ac0d5ef685a5d8 Mon Sep 17 00:00:00 2001
From: jack1142 <6032823+jack1142@users.noreply.github.com>
Date: Sat, 17 Jul 2021 02:34:19 +0200
Subject: [PATCH 4/6] Linkify the images
---
source/triaging-issues.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/source/triaging-issues.rst b/source/triaging-issues.rst
index a35ae5a..e6d29ff 100644
--- a/source/triaging-issues.rst
+++ b/source/triaging-issues.rst
@@ -10,6 +10,7 @@ Life cycle of an issue
----------------------
.. figure:: /_images/triaging.svg
+ :target: /_images/triaging.svg
#. The issue is waiting for triage (**Status: Needs Triage**)
#. The issue has been tagged with category, type and other relevant labels
From efe5b6d046aa3fec3e2823d7272230255ec0a6bb Mon Sep 17 00:00:00 2001
From: jack1142 <6032823+jack1142@users.noreply.github.com>
Date: Sun, 12 Sep 2021 23:03:19 +0200
Subject: [PATCH 5/6] Remove In Progress status, add No Activity From Author
resolution
---
source/_images/triaging.drawio | 150 ++++++++++++---------------------
source/_images/triaging.svg | 2 +-
source/triaging-issues.rst | 38 +++++----
3 files changed, 76 insertions(+), 114 deletions(-)
diff --git a/source/_images/triaging.drawio b/source/_images/triaging.drawio
index f48d32f..58b2293 100644
--- a/source/_images/triaging.drawio
+++ b/source/_images/triaging.drawio
@@ -1,11 +1,11 @@
-
+
-
+
-
+
@@ -112,44 +112,16 @@
-
-
+
+
-
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
@@ -160,76 +132,51 @@
-
+
+
+
+
-
-
+
+
+
+
+
+
+
-
+
-
-
-
-
-
-
-
-
-
-
-
+
-
-
+
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
-
+
-
+
-
-
-
-
-
-
@@ -239,10 +186,10 @@
-
+
-
+
@@ -293,13 +240,13 @@
-
+
-
+
@@ -317,38 +264,49 @@
-
+
-
+
-
-
-
-
-
-
-
+
-
+
-
-
+
+
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/source/_images/triaging.svg b/source/_images/triaging.svg
index 92d704c..5017c29 100644
--- a/source/_images/triaging.svg
+++ b/source/_images/triaging.svg
@@ -1,3 +1,3 @@
-
+
diff --git a/source/triaging-issues.rst b/source/triaging-issues.rst
index e6d29ff..363b465 100644
--- a/source/triaging-issues.rst
+++ b/source/triaging-issues.rst
@@ -50,13 +50,12 @@ Life cycle of an issue
#. A contributor or org member wants to work on the issue
- - If it is an org member, **Status: In Progress** label has been applied.
- - If it is a contributor, the issue remains with its current status until PR is made.
+ The issue remains with its current status until PR is made.
#. A PR addressing the issue has been made (**Status: PR Available**)
The automation automatically updates the labels if the issue was marked with
- **Status: Accepted - PRs Welcome** or **Status: In Progress** label.
+ **Status: Accepted - PRs Welcome** label.
- If PR gets closed (not merged), the issue goes back to its previous **Status**.
- If PR gets merged, the issue gets automatically closed by GitHub.
@@ -211,7 +210,8 @@ Author Feedback [T]_ The original author of the issue/PR needs to come bac
If this is an issue, it will be automatically commented on and labeled
with `No Activity ` label after 4 days of inactivity,
- and closed after another 3 days of no activity.
+ and closed with `Resolution: No Activity From Author `
+ after another 3 days of no activity.
Community Feedback Indicates that we are interested in hearing more from our community
before continuing with this.
@@ -316,25 +316,29 @@ Resolution
Describes why the issue was closed. Used for **all** closed issues and not actionable PRs.
-===================== ===========================================================================
-Resolution Description
-===================== ===========================================================================
-Duplicate There's another issue on the tracker that's pretty much the same thing.
+============================== ==================================================================
+Resolution Description
+============================== ==================================================================
+Duplicate There's another issue on the tracker that's
+ pretty much the same thing.
-External For issues that are outside this codebase. Might be about
- the lack of support from Discord.
+External For issues that are outside this codebase. Might be about
+ the lack of support from Discord.
-Fix Committed [A]_ The fix is checked in, but it has not been released yet.
+Fix Committed [A]_ The fix is checked in, but it has not been released yet.
-Fix Released [A]_ The fix has been released.
+Fix Released [A]_ The fix has been released.
-No Repro We couldn't get this to happen, or it stopped happening entirely.
+No Activity From Author [A]_ The issue needed a response from its author
+ but they did not respond.
-Won't Fix It's supposed to be this way or we're not interested in fixing this.
- There's probably a good reason.
+No Repro We couldn't get this to happen, or it stopped happening entirely.
-Not Actionable There is no action to be taken in response to this issue.
-===================== ===========================================================================
+Won't Fix It's supposed to be this way or we're not interested
+ in fixing this. There's probably a good reason.
+
+Not Actionable There is no action to be taken in response to this issue.
+============================== ==================================================================
.. _Changelog-Entry:
From bfae62773e98bd83d1c927223c3e1f4652132940 Mon Sep 17 00:00:00 2001
From: jack1142 <6032823+jack1142@users.noreply.github.com>
Date: Sun, 12 Sep 2021 23:05:18 +0200
Subject: [PATCH 6/6] Remove Docs and Tests types
---
source/triaging-issues.rst | 13 +------------
1 file changed, 1 insertion(+), 12 deletions(-)
diff --git a/source/triaging-issues.rst b/source/triaging-issues.rst
index 363b465..80c70fc 100644
--- a/source/triaging-issues.rst
+++ b/source/triaging-issues.rst
@@ -93,11 +93,7 @@ the information that is indicated by labels already.
Type
~~~~
-Describes the type of issue. Some issues might have multiple types, though it should be preferred
-to only label the issue with its main type(s).
-
-For example, a PR that adds a new functionality will most likely also update the documentation,
-but the PR should only be labeled with **Type: Feature** label.
+Describes the type of issue. Some issues might have multiple types.
======================= ======================================================================
Type Description
@@ -109,11 +105,6 @@ Dependency Update Adding/updating/removing some of Red's dependencies.
Deprecation This intends to deprecate some functionality.
-Docs Improvements to the docs (e.g. new topic, correction, etc.).
-
- Only used for issues and PRs that exclusively involve changes to
- the documentation.
-
Enhancement Something meant to enhance existing Red features.
Feature New feature or request.
@@ -130,8 +121,6 @@ Question This is a support question.
to Red's support server at https://discord.gg/red
Removal This intends to remove some functionality.
-
-Tests Used for issues/PRs that exclusively involve changes to the tests.
======================= ======================================================================
.. _Category: