Merge pull request #10683 from tetrapod00/bug-triage-update

Update Bug triage guidelines

Author: skyace65

contributing/workflow/bug_triage_guidelines.rst

@@ -12,35 +12,54 @@ hesitate to propose modifications to the following guidelines.
 Issues management
 -----------------
 
-GitHub proposes various features to manage issues:
+For issue management, we use the following GitHub processes:
 
--  Set one or several labels from a predefined list
--  Set one milestone from a predefined list
--  Keep track of the issue in the project dashboard
--  Define one contributor as "assignee" among the Godot engine
-   organization members
+- Each issue and pull request (PR) is categorized with a set of *labels*,
+  sometimes called "tags".
+- Each PR is assigned to a *milestone*. Some issues can also be assigned to a
+  *milestone* (see below).
+- Issues can have an *assignee*, who is a contributor among Godot maintainers.
+- Issues can be put in one or more *projects*.
+- PRs can be *linked* to one or more issues which they "fix" or "close".
 
-As the Godot engine organization on GitHub currently has a restricted
-number of contributors, we do not use assignees extensively for now. All
-contributors are welcome to take on any issue, if relevant after mentioning
-it on the issue ticket and/or discussing the best way to resolve it with
-other developers.
+We don't yet extensively use or rely on some other GitHub processes:
 
-For the time being, we do not use the project dashboard feature either.
+- Issue close reasons (completed, not planned, duplicate). While we use these,
+  it is not consistent, and older issues are all closed as "completed", so the
+  issue close reason should not be relied on.
+- Issue *types* (Bug, Feature, Task).
+- Issue *relationships*.
 
-As far as possible, we try to assign labels (and milestones, when relevant)
-to both issues and pull requests.
+We only use the assignees feature for Godot maintainers who are members of the
+Godot Engine GitHub organization, and even then not in all cases. For other
+issues, we track who is working on an issue by comments on the issue and linked
+pull requests. Most issues are available for any contributor to take on, after
+discussing it with other contributors. If you would like to work on an issue,
+first check that no one else is working on it, by looking for a linked pull
+request, a comment "claiming" the issue, or an assignee. If no one else is
+working on the issue, leave a comment on the issue to "claim" it and start
+working on it.
 
 Labels
 ~~~~~~
 
 The following `labels <https://github.com/godotengine/godot/labels>`__ are
 currently defined in the Godot repository:
 
-**Categories:**
+Categories:
+^^^^^^^^^^^
 
--  *Archived*: either a duplicate of another issue, or invalid. Such an
-   issue would also be closed.
+-  *Archived*: used to filter issues closed with a resolution other than "fixed".
+
+   - For issues, added to all issues that are not resolved by engine or
+     documentation changes. This includes duplicate issues, user error, or
+     reports in the wrong repository.
+     Since we don't rely on GitHub's issue close reasons (``completed``, ``not
+     planned``, and ``duplicate``), it is possible for an issue to be closed as
+     ``completed`` with the *Archived* label.
+   - For PRs, added to all closed PRs that are not merged. This includes superseded
+     or duplicate PRs, Git or GitHub mistakes, and valid PRs that end up not merged. 
+   
 -  *Breaks compat*: describes something that can only be fixed by breaking
    compatibility with existing projects.
 -  *Bug*: describes something that is not working properly.
@@ -66,12 +85,11 @@ currently defined in the Godot repository:
    should be filed on the `godot-docs <https://github.com/godotengine/godot-docs>`_ repository.
 -  *Enhancement*: describes a proposed enhancement to an existing
    functionality.
--  *Feature proposal*: describes a wish for a new feature to be
-   implemented. Note that the main Godot repository no longer accepts
-   feature requests. Please use
-   `godot-proposals <https://github.com/godotengine/godot-proposals>`__ instead.
-   PRs which add new features but do not have a corresponding proposal use this
-   label.
+-  *Feature proposal*: used for PRs adding new features which do not have a
+   corresponding proposal use this label. The label is removed when a feature
+   proposal is created and linked. The main Godot repository no longer accepts
+   feature requests as issues. Please use the `godot-proposals
+   <https://github.com/godotengine/godot-proposals>`__ repository instead.
 -  *For PR meeting*: the issue needs to be discussed in a pull request meeting.
    These meetings are public and are held on the `Godot Contributors Chat <https://chat.godotengine.org/>`_.
 -  *Good first issue*: the issue is *assumed* to be an easy one to fix, which makes
@@ -89,37 +107,41 @@ currently defined in the Godot repository:
 -  *Performance*: issues that directly impact engine or editor performance.
    Can also be used for pull requests that improve performance or add low-end-friendly options.
    Should not be coupled with *Usability*.
--  *Production*: Relates to the production team.
 -  *Regression*: the bug appeared after a stable release not exhibiting
    the bug was released.
 -  *Salvageable*: the pull request can't be merged due to design issues or
    merge conflicts and its author is not active anymore. However, it can still
-   be picked up by an external contributor to bring it to a mergeable state.
+   be picked up by another contributor to bring it to a mergeable state.
    To do so, you need to open a new pull request based on the original pull request.
+-  *Spam*: intentional spam issues, and extremely low-effort PRs. Used
+   sparingly, since we give contributors and users the benefit of the doubt. In
+   most cases, *Needs work* or *Archived* is more appropriate.
 -  *Tracker*: issue used to track other issues (like all issues related to
    the plugin system).
 -  *Usability*: issues that directly impact user usability. Should not be coupled with *Performance*.
 
-The categories are used for general triage of the issues. They can be
-combined in some way when relevant, e.g. an issue can be labelled
-*Enhancement* and *Usability* at the same time if it's an issue to improve
-usability. Or *Feature proposal* and *Discussion* if it's a non-consensual
-feature request, or one that is not precise enough to be worked on.
-At least one of the categories *Bug*, *Enhancement* or *Discussion* is used to
-describe an issue or pull request.
+The categories are used for general triage of the issues. They can be combined
+in some way when relevant, e.g. an issue can be labeled *Bug* and *Usability*
+at the same time if it's a bug that affects usability. Or *Enhancement* and
+*Discussion* if it's an improvement that requires discussion of the best
+approach. At least one of the categories *Bug*, *Enhancement*, or *Discussion*
+are used to describe an issue or pull request.
 
-**Topics:**
+Topics:
+^^^^^^^
 
--  *2D*: relates to 2D-specific issues. Should be coupled with one of the labels below, and should not be coupled with *3D*.
--  *3D*: relates to 3D-specific issues. Should be coupled with one of the labels below, and should not be coupled with *2D*.
+-  *2D*: relates to 2D nodes. Should be coupled with one of the labels
+   below, and should not be coupled with *3D*.
+-  *3D*: relates to 3D nodes. Should be coupled with one of the labels
+   below, and should not be coupled with *2D*.
 -  *Animation*: relates to the Animation system, editors and importers.
 -  *Assetlib*: relates to issues with the asset library.
 -  *Audio*: relates to the audio features (low- and high-level).
 -  *Buildsystem*: relates to building issues, either linked to the SCons
    buildsystem or to compiler peculiarities.
 -  *Codestyle*: relates to the programming style used within the codebase.
 -  *Core*: anything related to the core engine. Specific topics are split off separately as they crop up.
--  *Dotnet*: relates to the C# / Dotnet bindings.
+-  *Dotnet*: relates to the C# / .NET bindings.
 -  *Editor*: relates to issues in the editor (mainly UI).
 -  *Export*: relates to the export system and templates.
 -  *GDExtension*: relates to the GDExtension system for native extensions.
@@ -146,9 +168,10 @@ unthinkable to see issues that fit two bills. The general idea is that
 there will be specialized contributors teams behind all topics, so they
 can focus on the issues labelled with their team's topic.
 
-**Platforms:**
+Platforms:
+^^^^^^^^^^
 
-*Android*, *iOS*, *Linux*, *macOS*, *Web*, *Windows*
+*Android*, *iOS*, *LinuxBSD*, *macOS*, *Web*, *Windows*
 
 By default, it is assumed that a given issue applies to all platforms.
 If one of the platform labels is used, it is then exclusive and the
@@ -176,6 +199,12 @@ use the following `labels <https://github.com/godotengine/godot-docs/labels>`__:
    it a great fit for new contributors who want to become familiar with
    the code base. It should be removed while an active PR is available, that
    resolves this issue.
+-  *Linked demo PR*: the PR has a corresponding PR to the
+   `Godot Demo Projects <https://github.com/godotengine/godot-demo-projects>`__
+   repository which must be merged at the same time. Any changes to code in
+   tutorials that have a corresponding demo, such as :ref:`doc_your_first_2d_game`,
+   need to update both repositories so that the tutorial code stays in sync with
+   the completed demo.
 -  *Needs work*: the pull request needs additional work before it can be merged.
 -  *Python*: Pull requests that update Python code.
 -  *Salvageable*: the pull request can't be merged due to design issues or
@@ -184,8 +213,11 @@ use the following `labels <https://github.com/godotengine/godot-docs/labels>`__:
    To do so, you need to open a new pull request based on the original pull request.
 -  *Tracker*: issue used to track other issues (like all issues related to
    the plugin system).
+-  *Waiting on PR merge*: the PR documents an engine PR that has not been merged
+   yet.
 
-**Area:**
+Area:
+^^^^^
 
 -  *About*: Issues and PRs related to the About section of the documentation and other general articles.
 -  *Class reference*: the issue is about the class reference, not a documentation page.
@@ -194,7 +226,8 @@ use the following `labels <https://github.com/godotengine/godot-docs/labels>`__:
 -  *Getting started*: Issues and PRs related to the Getting Started section of the documentation.
 -  *Manual*: Issues and PRs related to the Manual/Tutorials section of the documentation.
 
-**Content:**
+Content:
+^^^^^^^^
 
 -  *Images*: Issues and PRs involving outdated or incorrect images in articles.
 -  *Example code*: Issues and PRs involving writing or updating code examples.
@@ -204,23 +237,51 @@ use the following `labels <https://github.com/godotengine/godot-docs/labels>`__:
 -  *Redirect*: Issues and PRs involving moving content and adding a redirect rule on the backend.
 -  *Website*: Issues related to adding website features and fixing bugs, whether on the front or back-end,
 
-**Topic:**
+Topic:
+^^^^^^
 
 The available topics describe the same content as the topics in the main
 repository.
 
 Milestones
 ~~~~~~~~~~
 
-`Milestones <https://github.com/godotengine/godot/milestones>`_ correspond to
-planned future versions of Godot for which there is an existing roadmap. Issues
-that fit in the said roadmap should be filed under the corresponding milestone;
-if they don't correspond to any current roadmap, they should be left without
-milestone. As a rule of thumb, an issue corresponds to a given milestone if it
-concerns a feature that is new in the milestone, or a critical bug that can't be
-accepted in any future stable release, or anything that Juan wants to work on
-right now. :)
-
-Contributors are free to pick issues regardless of their assigned milestone;
-if a fix is proposed for a bug that was not deemed urgent and thus without
-milestone, it would likely still be very welcome.
+`Milestones <https://github.com/godotengine/godot/milestones>`_ are used for
+some issues and all PRs.
+
+We have milestones for specific minor engine versions, like ``4.5`` and ``4.6``,
+as well as general milestones for major engine versions, like ``3.x`` and
+``4.x``. In the ``godot-proposals`` repo, we also have a ``5.0`` milestone for
+compatibility-breaking changes that will be considered for Godot 5.0, in many
+years.
+
+Issues are assigned to the current development milestone, such as ``4.5``, if
+they are related to features introduced in that engine version, or are bugs
+(regressions) in that version. Additionally, all issues completed during the
+development of that engine version are added to the milestone, so that users can
+see at a glance in which minor version an issue was first fixed. We don't always
+use the ``4.x`` milestone for issues, since by default all issues are related to
+Godot 4.x. However, we do use the ``3.x`` milestone to mark issues that are
+specific to Godot 3.x.
+
+All pull requests are assigned to a milestone. By default, enhancement and
+feature PRs are assigned to the ``4.x`` milestone, and bugs are assigned to the
+current development milestone, such as ``4.5``. Towards the end of the minor
+version's development, PRs currently in that milestone are reassessed. If
+a PR is no longer being considered for that version, it is reassigned to either the
+major version milestone (``4.x``), or the next minor version milestone (such as
+``4.6``).
+
+Pull requests in the ``4.x`` milestone are reassigned to the current minor
+engine version, such as ``4.5``, when the review process is complete, and the
+production team decides that the PR is ready to be merged soon. Note that
+this usually requires more than one approving review.
+
+The milestone assigned to a PR is a goal, not a guarantee. New features and
+enhancements are merged when they are ready. While reviewers and maintainers do
+their best to review PRs in time for the current version, at some point we reach
+the beta, feature freeze, and then release; and existing PRs are reassigned to
+the next minor version, or to ``4.x``. As a rule, we assign new features to the
+``4.x`` milestone initially to avoid continually reassigning a PR from version
+to version. However, a PR being in ``4.x`` does not mean it won't be merged;
+it's just the default for new features.