From 226895f206bc04167a60032992137226c934ce44 Mon Sep 17 00:00:00 2001 From: A Thousand Ships <96648715+AThousandShips@users.noreply.github.com> Date: Tue, 25 Nov 2025 15:25:50 +0100 Subject: [PATCH] [Triage] Improve the release priority page Renamed from release blockers and adding more workflow details --- index.rst | 2 +- triage/release_blockers.rst | 35 ----------- triage/release_priorities.rst | 112 ++++++++++++++++++++++++++++++++++ triage/workflow.rst | 10 +-- 4 files changed, 118 insertions(+), 41 deletions(-) delete mode 100644 triage/release_blockers.rst create mode 100644 triage/release_priorities.rst diff --git a/index.rst b/index.rst index 7b87c86..aa9492a 100644 --- a/index.rst +++ b/index.rst @@ -44,7 +44,7 @@ for your topic of interest. You can also use the search function in the top-left triage/about triage/workflow triage/guidelines - triage/release_blockers + triage/release_priorities triage/sprint_instructions .. toctree:: diff --git a/triage/release_blockers.rst b/triage/release_blockers.rst deleted file mode 100644 index 1511f96..0000000 --- a/triage/release_blockers.rst +++ /dev/null @@ -1,35 +0,0 @@ -.. _doc_bug_triage_release_blockers: - -Release blocker tracking -======================== - -Release blockers are issues that we aim to fix before we release the -next version. There are a few different things to consider when -determining if an issue is a release blocker or not. Generally any bug -that has appeared during the current cycle should be considered release -blockers (and assigned the “regression” label), if the issue isn’t -considered critical it will marked as not critical, see -`severity <#severity>`__ below. - -Issues with new features can also be considered release blockers. This -is because once a feature is part of a released version (and isn’t -considered experimental) it is much harder to change how that feature -works without breaking compatibility (see the `release policy page `__). -This means that fixing issues, especially minor issues that wouldn’t be -critical otherwise, should be done early to avoid compatibility issues -later. - -Release blockers have their own project, `4.x Release Blockers `__. - -Severity --------- - -Release blockers should also be assigned a severity, this is usually -handled by either the production team or the specific :ref:`area maintainers `, so this is only a rough -outline to use to assign this if you are able: - -* *Not Critical*: For issues that do not have to be fixed before the next release, but would be good if we can to reduce newly introduced issues. -* *Bad*: For issues that should be fixed before the next release, but are less critical. -* *Very bad*: Like *Bad* but worse. -* *Release Blocker*: For issues that we absolutely need to fix before releasing. These include issues that severely hurt engine usability, breaks existing functionality, or are new features that don’t work. In some cases less critical bugs can be considered a release blocker if it involves new API and delaying fixing the problem means restricting the solution due to compatibility issues. -* *Immediate Blocker*: For issues that should be solved as soon as possible, rather than before release. This includes issues that make the engine completely unusable, breaks the buildsystem, or are dangerous or damaging (such as security issues or privacy issues). diff --git a/triage/release_priorities.rst b/triage/release_priorities.rst new file mode 100644 index 0000000..d093f07 --- /dev/null +++ b/triage/release_priorities.rst @@ -0,0 +1,112 @@ +.. _doc_bug_triage_release_priorities: + +Release priority tracking +========================= + +Release priorities are issues that we aim to fix before we release the +next version. There are a few different things to consider when +determining if an issue is a release priority or not. + +See below for an explanation of how to +`identify release priorities <#identifying-release-priority-issues>`__, +and how to assign a `severity <#severity>`__ to them. When in doubt, mark issues as +release priorities. We can always remove issues from the list, but it is critical +that we know about potentially important issues before releasing a version. + +Release priorities are tracked in a public project, `4.x Release Priorities `__. + +Identifying release priority issues +----------------------------------- + +The following is a checklist to determine if an issue is a release priority or not. + +If an issue is old (over 6 months), and hasn't gotten worse, or gotten new duplicate issues +or users that report having encountered the issue, it is likely not a release priority. + +If you are unsure if an issue is a priority, prefer to flag issues as priorities, but +add a note in the tracker clarifying this. + +Is it a regression? +~~~~~~~~~~~~~~~~~~~ + +Any regression in the current release cycle is considered a release priority. A regression +is any feature or part of the engine that used to work but no longer works, for example something +that worked in 4.5.1 but doesn't work in 4.6.dev2. Regressions are also assigned the “regression” label. + +Regressions from previous cycles can also be considered release priorities depending on when they happened +and how severe they are (for example, a bug that occurs in 4.5 but not 4.4 can be considered a release priority +during the 4.6 dev cycle). + +Regressions should be fixed as soon as possible. Regressions from previous cycles should also be backported +where appropriate. + +It is important to flag anything that looks like a regression as a priority. Some changes to existing behavior +is intentional, but the relevant maintainers should make this evaluation and will remove the issue if it +isn't a regression. And even if the change in behavior is intentional, there might be missing compatibility code +or documentation for the change which needs to be evaluated. + +Is it a crash with significant user impact? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An engine issue that causes crashes or freezes and affects a lot of users is a release priority. This is +mostly determined based on many users reporting the same issue, or issues that remain open over a long period of time. + +This often involves graphics issues and can be hard to identify or result in unclear bug reports, identifying +if the time the issues started line up with recent graphics driver updates can be a good indicator. + +Is it a showstopper bug? +~~~~~~~~~~~~~~~~~~~~~~~~ + +Showstopper bugs are release priorities. A showstopper issue is any issue that prevents users from performing key tasks, +like using certain parts of the engine, or that causes loss of data or work, and that has no workaround or that causes +significant workflow disruption. + +Examples of showstopper issues are: +* Parts of the editor or engine that do not work, or are difficult to use, including only on some platforms: + - Changes to the animation system causing errors when using animation features, + - Improvements to the way the editor generates previews and thumbnails causing severe performance regressions, + - Changes to the export process causing C# code to not be exported. +* Errors that cause loss of data or work, for example deleting or corrupting project files. +* Issues using or importing file formats. +* Issues with specific hardware, like controllers not working or rendering being broken on certain graphics hardware. + +Is it a bug in a new feature? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Issues in new features should be priorities even if the issue itself isn't critical otherwise. +Fixing issues in new features might require changing significant parts of the feature in ways that break compatibility, +or it might be difficult to fix the issue without breaking compatibility. This means that fixing issues in new features, +and making sure issues in new features are evaluated by maintainers, is especially important. + +This also includes issues or enhancements involving code that was already changed in a compatibility breaking way in the +current release cycle, to avoid breaking compatibility in two separate versions when possible. + +Is it a security issue? +~~~~~~~~~~~~~~~~~~~~~~~ + +Any security issue is a release priority. Security issues include things like vulnerabilities in engine or third-party code, +like remote code execution, but also engine issues that cause damage or data loss for the user, like the editor deleting +files outside the project directory. + +If something seems like a serious security issue, please contact Godot's security team directly immediately +([security@godotengine.org](mailto:security@godotengine.org)). The team will take the appropriate steps to address the issue. + +Is it a new platform requirement? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Any new platform requirement that will affect users is a release priority. This includes things like Google Play changing +the required target API for Android, or operating system updates or changes that affect users or exported projects on those platforms. + +Severity +-------- + +Release priorities should also be assigned a severity, this is usually +handled by either the production team or the specific :ref:`area maintainers `, so this is only a rough +outline to use to assign this if you are able: + +* *Immediate Blocker*: This must be resolved before the next dev/beta/RC snapshot. +* *Release Blocker*: This must be resolved as soon as possible, and before entering the RC phase or the next RC snapshot. +* *Very bad*: This is a critical issue which either affects a lot of users, or is a showstopper for a significant part of the userbase. +* *Bad*: This is an annoying issue which may affect a lot of users, but isn’t a showstopper. +* *Not Critical*: This is an overall minor issue, but which may affect a new feature and would be nice to fix before stable. +* *Unassessed*: This issue was added to the tracker but without assessing its severity. This needs to be evaluated by maintainers as it may be a release priority. diff --git a/triage/workflow.rst b/triage/workflow.rst index 06be5d6..9ce5a60 100644 --- a/triage/workflow.rst +++ b/triage/workflow.rst @@ -23,7 +23,7 @@ Triage checklist author to add the missing information. - `Check for duplicates <#check-for-duplicates>`__. - Check if the issue is a recent regression. If it is, add it to the - :ref:`release blocker tracker ` and + :ref:`release priorities ` and mark it as a “regression”. - Add initial labels. - `Assign a milestone <#assigning-milestones>`__ if relevant. @@ -78,7 +78,7 @@ having tested development versions) please either ask the author to test with a stable version or test the bug yourself. If it *doesn’t* occur on a past release it is considered a regression and should be tagged with the “regression” label, and should also be added to the “4.x Release -Blockers” project. See :ref:`doc_bug_triage_release_blockers` for details. +Priorities” project. See :ref:`doc_bug_triage_release_priorities` for details. Try to tag an issue as specifically as possible, adding “needs testing” and “needs work” if necessary. Don’t worry about misidentifying issues, @@ -104,20 +104,20 @@ Note that this is for assigning milestones to *open* issues, please see and milestones. Below is an outline of the different milestones we use, but as a general -rule you can assume that issues that aren’t release blockers, or +rule you can assume that issues that aren’t release priorities, or specific to ``3.x``, shouldn’t have milestones assigned. For the ``master`` branch: * ``4.x``: For Godot 4 in general, i.e. the ``master`` branch. We do not use the ``4.x`` milestone on issues, issues with no milestone are assumed to be relevant for the current development cycle. -* *The current development version*: Should be assigned to issues that are :ref:`release blockers `, or otherwise prioritized for the current version. +* *The current development version*: Should be assigned to issues that are :ref:`release priorities `, or otherwise prioritized for the current version. * *The next release version*: When we enter feature freeze we usually create a new milestone used for PRs that are approved but won’t make it into the current release, this milestone is not used for issues. * *Older Godot 4 versions*: This is used for issues that are only relevant for this specific version (or older versions), but not any newer version. An example of this would be an issue that was solved in ``4.5`` as part of an enhancement, but that enhancement cannot be cherry-picked for ``4.4`` and a separate issue is necessary to track the specific solution for ``4.4`` (and older, if relevant). For such issues it can also be relevant to add “[4.4]” at the beginning of the issue title to help clarify it is specific to this version. For Godot 3: * ``3.x``: For the ``3.x`` branch in general. Used for issues that are only relevant for the ``3.x`` version, and occurs on the current development version of ``3.x``. For these issues it can also help to add “[3.x]” at the beginning of the issue title to help identifying the issue. -* Other Godot 3 milestones work the same way as for the ``master`` branch, except we do not track release blockers for ``3.x``. +* Other Godot 3 milestones work the same way as for the ``master`` branch, except we do not track release priorities for ``3.x``. Testing an Issue ----------------