Update Bug triage guidelines #10683

tetrapod00 · 2025-02-13T20:09:17Z

Work in progress.

Update the list of labels to match the current list.
List which GitHub features we use in a more up to date way
Clarify when archived is used
Use sphinx headers instead of bold :)
Rewrote entirely the milestones description. While it was true in palces, it's wrong enough that it deserved a rewrite from first principles.

tetrapod00 · 2025-02-14T04:55:38Z

contributing/workflow/bug_triage_guidelines.rst

+Godot engine GitHub organization, and even then not in all cases. Any contributor
+is welcome to take on any issue, after discussing it with other contributors.
+If you would like to pick up an issue (and no one else is working on it), all
+you have to do is leave a comment in the issue.


We could write some additional content about the general workflow here.

tetrapod00 · 2025-02-14T04:56:19Z

contributing/workflow/bug_triage_guidelines.rst

+the next minor version, or to ``4.x``. As a rule, we assign new features to
+``4.x`` version initially to avoid continually re-triaging 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.


This paragraph needs the most attention to set expectations.

tetrapod00 · 2025-02-14T05:08:28Z

contributing/workflow/bug_triage_guidelines.rst


 Labels
 ~~~~~~

 The following `labels <https://github.com/godotengine/godot/labels>`__ are
 currently defined in the Godot repository:

-**Categories:**
+Categories:
+^^^^^^^^^^^


I went through the whole list, and I consider the current descriptions to be acceptable, complete, and correct to my knowledge.

But I'm sure we could improve these further if we wanted to?

AThousandShips

Looks like a great start! Will do a more in-depth review of this soon but it looks good

contributing/workflow/bug_triage_guidelines.rst

AThousandShips

Generally this looks great, will do another pass soon and see what information might be missing from the sections expanded on currently

contributing/workflow/bug_triage_guidelines.rst

AThousandShips · 2025-02-17T15:58:42Z

contributing/workflow/bug_triage_guidelines.rst

+-  *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*.


These two are supposed to be related to 2D and 3D nodes specifically

From what I've seen it's used frequently along with topic:rendering, including about features that aren't actually nodes

Yes but what I'm describing is the intended use

contributing/workflow/bug_triage_guidelines.rst

AThousandShips · 2025-02-17T16:00:27Z

contributing/workflow/bug_triage_guidelines.rst

+Godot engine GitHub organization, and even then not in all cases. Any contributor
+is welcome to take on any issue, after discussing it with other contributors.
+If you would like to pick up an issue (and no one else is working on it), all
+you have to do is leave a comment in the issue.


Suggested change

you have to do is leave a comment in the issue.

you have to do is leave a comment on the issue.

Also we might want to clarify here that there are issues that aren't necessarily open for general contributions, but should always be handled by maintainers, so might want to not state explicitly that anyone is welcome to take on any issue at least

AThousandShips · 2025-02-17T16:03:22Z

contributing/workflow/bug_triage_guidelines.rst

+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 minor version milestone, such as ``4.5``. Towards the end of a minor
+version's development, PRs currently in the minor version milestone are
+reassigned to either the major version milestone (``4.x``), or the next minor
+version milestone (such as ``4.6``).


This section should make it clear that PRs are reassigned only if they are not considered for the version, as this makes it sound like all PRs are moved before the version is released

AThousandShips · 2025-02-17T16:04:02Z

contributing/workflow/bug_triage_guidelines.rst

+When a pull request is approved and merged, it is moved from ``4.x`` to the
+milestone for the current minor engine version, such as ``4.5``.


This happens before it is merged, when the review process is complete and the production team decides it is ready to go

This is tricky to word well, since:

We don't always follow the prescriptive guide for what to put in 4.4 vs 4.x, or when to move PRs

The production team "approval" is somewhat opaque

Being in 4.4 and having multiple relevant approvals still doesnt always guarantee "merge soon"

So I'm not sure whether to write the prescriptive ideal case or to hedge a bit to account for some inconsistency in usage of milestones.

That aside we normally don't merge PRs that's on a .x milestone, either this part should be removed entirely or it should say that a PR is moved to a specific milestone when it's considered ready to merge, but regardless the specific order of events here doesn't reflect our process

tetrapod00 · 2025-02-17T19:32:07Z

Addressed the review, but left conversations unresolved since a lot of this is subjective

AThousandShips · 2025-02-18T13:01:53Z

I think this looks good now, will do a pass later today and see what areas might be missing

AThousandShips · 2025-02-24T09:54:45Z

Sorry for the delay things came up, will give this a final pass today and I think it should be a good start to improving things

AThousandShips

With the exception of a few notes I think this is ready, this is a major improvement and any areas we might still be missing can be improved on in future PRs

contributing/workflow/bug_triage_guidelines.rst

AThousandShips · 2025-02-24T14:37:20Z

contributing/workflow/bug_triage_guidelines.rst

+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 minor version milestone, such as ``4.5``. Towards the end of the minor
+version's development, PRs currently in the ``4.5`` milestone are reassessed. If


Suggested change

version's development, PRs currently in the ``4.5`` milestone are reassessed. If

version's development, PRs currently in that milestone are reassessed. If

To avoid confusion

Makes sense. I had it like this before anyway, but thought it might be clearer with a specific 4.5 example. I changed it back

contributing/workflow/bug_triage_guidelines.rst

akien-mga

Looks great to me!

Thanks so much for updating this, I've kept telling people that this page was probably outdated for years without actually taking the time to update it... I see now that there had already been significant updates, and this just rounds it up quite well!

akien-mga · 2025-02-27T21:39:16Z

contributing/workflow/bug_triage_guidelines.rst

-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


Suggested change

Godot engine GitHub organization, and even then not in all cases. For other

Godot Engine GitHub organization, and even then not in all cases. For other

akien-mga · 2025-02-27T21:41:22Z

contributing/workflow/bug_triage_guidelines.rst


-  *Archived*: either a duplicate of another issue, or invalid. Such an
-   issue would also be closed.
+-  *Archived*: used to filter closed issues.


Suggested change

- *Archived*: used to filter closed issues.

- *Archived*: used to filter issues closed with a resolution other than "fixed".

akien-mga · 2025-02-27T21:43:44Z

contributing/workflow/bug_triage_guidelines.rst

-   `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


For consistency with other items:

Suggested change

- *Feature proposal*: Used for PRs adding new features which do not have a

- *Feature proposal*: used for PRs adding new features which do not have a

akien-mga · 2025-02-27T21:45:51Z

contributing/workflow/bug_triage_guidelines.rst

+-  *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


There seems to have been a shift in understanding of this label, this wasn't what it meant originally.

The description of enhancement mentions that it's for changes to existing functionality, so feature proposal should cover the addition of new features - whether or not they have a linked proposal.

It should probably be renamed to new feature, the name dates back to when we had feature proposals as issues in the main tracker.

Yeah, I updated it recently to match the observed usage. Personally I do think it would be good to distinguish between new features and enhancements, as originally intended and as you're proposing here.

But this sounds like a case where we should change how the label is applied in practice before changing the docs for it?

akien-mga · 2025-02-27T21:51:35Z

contributing/workflow/bug_triage_guidelines.rst

-   organization members
+- Each issue and pull request (PR) is categorized with a set of *labels*,
+  sometimes called "tags".
+- Each issue and PR is assigned to a *milestone*.


Suggested change

- Each issue and PR is assigned to a *milestone*.

- Each PR is assigned to a *milestone*. Some issues can also be assigned to a *milestone* (see below).

akien-mga · 2025-02-27T21:53:15Z

contributing/workflow/bug_triage_guidelines.rst

+compatibility-breaking changes that will be considered for Godot 5.0, in many
+years.
+
+Issues are assigned to a milestone, such as ``4.5``, if they are related to


Suggested change

Issues are assigned to a milestone, such as ``4.5``, if they are related to

Issues are assigned to current development milestone, such as ``4.5``, if they are related to

akien-mga · 2025-02-27T21:53:45Z

contributing/workflow/bug_triage_guidelines.rst

+
+Issues are assigned to a 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 that engine version are added


Suggested change

version. Additionally, all issues completed during that engine version are added

version. Additionally, all issues completed during the development of that engine version are added

akien-mga · 2025-02-27T21:54:29Z

contributing/workflow/bug_triage_guidelines.rst

+
+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 minor version milestone, such as ``4.5``. Towards the end of the minor


Suggested change

current minor version milestone, such as ``4.5``. Towards the end of the minor

current development milestone, such as ``4.5``. Towards the end of the minor

akien-mga · 2025-02-27T21:57:27Z

contributing/workflow/bug_triage_guidelines.rst

+Issues are assigned to a 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 that engine version are added
+to the milestone. We don't always use the ``4.x`` milestone for issues, since by


Suggested change

to the milestone. We don't always use the ``4.x`` milestone for issues, since by

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

tetrapod00 added enhancement area:contributing Issues and PRs related to the Contributing/Development section of the documentation labels Feb 13, 2025

tetrapod00 requested a review from AThousandShips February 13, 2025 20:09

tetrapod00 force-pushed the bug-triage-update branch from e3d0a0e to 3df3f83 Compare February 14, 2025 04:46

tetrapod00 commented Feb 14, 2025

View reviewed changes

AThousandShips reviewed Feb 14, 2025

View reviewed changes

contributing/workflow/bug_triage_guidelines.rst Outdated Show resolved Hide resolved

tetrapod00 force-pushed the bug-triage-update branch 3 times, most recently from fe81f76 to 4cf2b65 Compare February 15, 2025 21:25

AThousandShips reviewed Feb 17, 2025

View reviewed changes

tetrapod00 force-pushed the bug-triage-update branch 2 times, most recently from 6b0b807 to 9657032 Compare February 17, 2025 19:31

tetrapod00 marked this pull request as ready for review February 20, 2025 04:25

AThousandShips approved these changes Feb 24, 2025

View reviewed changes

Update Bug triage guidelines

adc23c6

tetrapod00 force-pushed the bug-triage-update branch from 9657032 to adc23c6 Compare February 24, 2025 17:21

akien-mga approved these changes Feb 27, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update Bug triage guidelines #10683

Update Bug triage guidelines #10683

tetrapod00 commented Feb 13, 2025 •

edited

Loading

tetrapod00 Feb 14, 2025

tetrapod00 Feb 14, 2025

tetrapod00 Feb 14, 2025 •

edited

Loading

AThousandShips left a comment

AThousandShips left a comment

AThousandShips Feb 17, 2025

tetrapod00 Feb 17, 2025

AThousandShips Feb 17, 2025

AThousandShips Feb 17, 2025

AThousandShips Feb 17, 2025

AThousandShips Feb 17, 2025

tetrapod00 Feb 17, 2025

AThousandShips Feb 18, 2025

tetrapod00 commented Feb 17, 2025

AThousandShips commented Feb 18, 2025

AThousandShips commented Feb 24, 2025

AThousandShips left a comment

AThousandShips Feb 24, 2025

tetrapod00 Feb 24, 2025

akien-mga left a comment

akien-mga Feb 27, 2025

akien-mga Feb 27, 2025

akien-mga Feb 27, 2025

akien-mga Feb 27, 2025

tetrapod00 Feb 27, 2025

akien-mga Feb 27, 2025

akien-mga Feb 27, 2025

akien-mga Feb 27, 2025

akien-mga Feb 27, 2025

akien-mga Feb 27, 2025

	you have to do is leave a comment in the issue.
	you have to do is leave a comment on the issue.

		When a pull request is approved and merged, it is moved from ``4.x`` to the
		milestone for the current minor engine version, such as ``4.5``.

	version's development, PRs currently in the ``4.5`` milestone are reassessed. If
	version's development, PRs currently in that milestone are reassessed. If

	Godot engine GitHub organization, and even then not in all cases. For other
	Godot Engine GitHub organization, and even then not in all cases. For other

	- Archived: used to filter closed issues.
	- Archived: used to filter issues closed with a resolution other than "fixed".

	- Feature proposal: Used for PRs adding new features which do not have a
	- Feature proposal: used for PRs adding new features which do not have a

		- 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

	- Each issue and PR is assigned to a milestone.
	- Each PR is assigned to a milestone. Some issues can also be assigned to a milestone (see below).

	Issues are assigned to a milestone, such as ``4.5``, if they are related to
	Issues are assigned to current development milestone, such as ``4.5``, if they are related to

	version. Additionally, all issues completed during that engine version are added
	version. Additionally, all issues completed during the development of that engine version are added

	current minor version milestone, such as ``4.5``. Towards the end of the minor
	current development milestone, such as ``4.5``. Towards the end of the minor

	to the milestone. We don't always use the ``4.x`` milestone for issues, since by
	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

Update Bug triage guidelines #10683

Are you sure you want to change the base?

Update Bug triage guidelines #10683

Conversation

tetrapod00 commented Feb 13, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tetrapod00 Feb 14, 2025 • edited Loading

Choose a reason for hiding this comment

AThousandShips left a comment

Choose a reason for hiding this comment

AThousandShips left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tetrapod00 commented Feb 17, 2025

AThousandShips commented Feb 18, 2025

AThousandShips commented Feb 24, 2025

AThousandShips left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

akien-mga left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tetrapod00 commented Feb 13, 2025 •

edited

Loading

tetrapod00 Feb 14, 2025 •

edited

Loading