From f26705038962263da992bf22d923e87e8dbc509c Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Wed, 12 Aug 2026 13:52:53 +0100 Subject: [PATCH 1/2] Some updates and restructuring of the 'Triaging an issue' --- triage/labels.rst | 1 + triage/triaging.rst | 89 ++++++++++++++++++++++++++++++++++----------- 2 files changed, 69 insertions(+), 21 deletions(-) diff --git a/triage/labels.rst b/triage/labels.rst index 96e0d8f58e..3251a384cf 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -121,6 +121,7 @@ Other labels * :gh-label:`easy`: for issues that are considered easy. * :gh-label:`infra`: for issues related to the infrastructure of the project (for example, GitHub Actions, dependabot, the buildbots). +* :gh-label:`invalid`: for marking spam issues/PRs. * :gh-label:`pending`: for issues/PRs that will be closed unless further feedback is provided. * :gh-label:`release-blocker`/:gh-label:`deferred-blocker`: for issues/PRs diff --git a/triage/triaging.rst b/triage/triaging.rst index 1387fa5177..3073ca8d7b 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -4,25 +4,51 @@ Triaging an issue ================= -This section of the devguide documents the :ref:`issue tracker ` for -users and developers. +This section of the devguide documents triaging issues on the :ref:`issue tracker +`. + +Around the clock, new issues are being opened and existing ones are being +updated. Every issue needs to be triaged to make sure everything runs smoothly. Checklist for triaging ====================== * Read the initial message and the comments. +* :ref:`Search the tracker ` to check that the issue + isn't a duplicate. If it is, use GitHub's :guilabel:`Close as duplicate` + option and select the issue it duplicates. * Check that the title is reasonably concise, while including enough specifics so that those scanning the list of issues can quickly identify its topic. * For pull requests, ensure that the corresponding issue is added before the title (:samp:`gh-NNNNN: {Title}`). -* Set all the relevant :ref:`labels `. -* Where appropriate, set the :guilabel:`Assignees`, :guilabel:`Reviewers`, - :guilabel:`Project` fields, and possibly @mention relevant people. +* Set all the relevant :ref:`labels `. +* Where appropriate, set the :guilabel:`Assignees`, :guilabel:`Reviewers`, and + :guilabel:`Project` :ref:`fields `, and possibly @mention + relevant people. * You might also leave a brief comment about the proposed next action needed. If there is a long message list, a summary can be very helpful. -* If the issue is clearly invalid (unrelated to CPython, duplicate, spam, and - so on), you can use GitHub's "Close as not planned" option. +* If the issue is clearly invalid (unrelated to CPython, spam, and + so on), you can use GitHub's :guilabel:`Close as not planned` option + and apply the :gh-label:`invalid` label. + + +.. _triage-fields: + +Issue fields +============ + +These fields can be set in the sidebar of issues and pull requests. + + +.. _triage-labels: + +Labels +------ + +Labels are the main way of categorizing issues and automating certain actions on +pull requests. Set all that apply. See :ref:`gh-labels` for more information. + Assignees --------- @@ -35,11 +61,33 @@ forward without their help; for example, they need to make a technical decision how to proceed. Also consult the :ref:`experts` as certain stdlib modules should always be assigned to a specific person. -Note that in order to assign an issue to someone, that person **must** be +Note that in order to assign an issue to someone, that person **must** have at least triage permissions in the repository. -.. The Assignees subsection was copied from the labels.rst page in #930. - For consistency, the other fields mentioned above should be documented too. + +Reviewers +--------- + +This field is used to request a review from specific people. + +In most cases there is nothing to do, as the maintainers listed in the +:cpy-file:`.github/CODEOWNERS` file are automatically requested to review +pull requests touching the files they maintain. Otherwise, consult the +:ref:`experts` to find someone with a working knowledge of the affected area +or platform. + +If the person you have in mind doesn't show up in the :guilabel:`Reviewers` +dropdown (usually because they don't have the required permissions in the +repository), @mention them in a comment instead. + + +Project +------- + +`GitHub projects `__ are used to track +work on a specific module, platform, or interest area across issues and pull +requests. Add all the relevant ones. Note that several are added automatically +when the corresponding :ref:`label ` is added. .. _helptriage: @@ -52,9 +100,6 @@ structured and you are comfortable with the workflow, a great way to contribute is to help triage issues. Do realize, though, that experience working on Python is needed in order to effectively help triage. -Around the clock, new issues are being opened on the :ref:`issue tracker -` and existing issues are being updated. Every issue needs to be -triaged to make sure everything runs smoothly. Classifying reports ------------------- @@ -63,14 +108,14 @@ For bugs, an issue needs to: * clearly explain the bug so it can be reproduced * include all relevant platform details -* state what version(s) of Python are affected by the bug. +* state what versions of Python are affected by the bug. These are things you can help with once you have experience developing for Python: * Try reproducing the bug: if it is not explained clearly - enough for you to reproduce it, then there is a good chance a core developer - won't be able to either. + enough for you to reproduce it, then there is a good chance a core team + member won't be able to either. * See if the issue happens on a different Python version: it is always helpful to know if a bug not only affects the in-development version of Python, but whether it also affects other versions in maintenance mode. @@ -78,8 +123,9 @@ Python: Python's test suite, having that written can be very helpful. This is all helpful as it allows members of the :ref:`triage team ` -to properly classify an issue so it can be handled by the right core developers -in a timely fashion. +to properly classify an issue so it can be handled by the right core team +members in a timely fashion. + Reviewing pull requests ----------------------- @@ -88,19 +134,20 @@ If an issue has a linked pull request that has not been reviewed, you can help by making sure the pull request: * is a good solution to the problem it is trying to solve -* follows the style guides (:pep:`7`, :pep:`8`, :ref:`style-guide`, etc.) +* follows the style guides (for example, :pep:`7`, :pep:`8`, and :ref:`style-guide`) * includes proper tests * includes proper documentation changes * includes a :ref:`NEWS entry ` (if needed) * doesn't have conflicts with the ``main`` branch * :ref:`doesn't have failing CI checks ` -Doing all of this allows core developers and :ref:`triagers ` +Doing all of this allows core team members and :ref:`triagers ` to more quickly look for subtle issues that only people with extensive -experience working on Python's code base will notice. +experience working on Python's codebase will notice. See also :ref:`committing`. + Finding an issue you can help with ---------------------------------- From d8b88b0a209126fa3b28dd3a8d48f9aa59cff118 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Thu, 13 Aug 2026 12:41:41 +0100 Subject: [PATCH 2/2] Ezio's rewording suggestion Co-authored-by: Ezio Melotti --- triage/triaging.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/triage/triaging.rst b/triage/triaging.rst index 3073ca8d7b..22c1c5b745 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -4,11 +4,8 @@ Triaging an issue ================= -This section of the devguide documents triaging issues on the :ref:`issue tracker -`. - -Around the clock, new issues are being opened and existing ones are being -updated. Every issue needs to be triaged to make sure everything runs smoothly. +Every issue on the :ref:`issue tracker ` needs to be triaged to make +sure everything runs smoothly. This section covers what that involves. Checklist for triaging