Skip to content

Updates and restructuring of the 'Triaging an issue' #1878

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
StanFromIreland wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Updates and restructuring of the 'Triaging an issue' #1878

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions triage/labels.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
89 changes: 68 additions & 21 deletions triage/triaging.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,51 @@
Triaging an issue
=================

This section of the devguide documents the :ref:`issue tracker <tracker>` for
users and developers.
This section of the devguide documents triaging issues on the :ref:`issue tracker
<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.

@ezio-melotti ezio-melotti Aug 12, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These two paragraphs could be merged into a single, more concise, paragraph. Something like:

Every issue needs to be triaged to make sure everything runs smoothly. This section describes how to do it



Checklist for triaging
======================

* Read the initial message and the comments.
* :ref:`Search the tracker <searching-gh-issues>` 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 <gh-labels>`.
* Where appropriate, set the :guilabel:`Assignees`, :guilabel:`Reviewers`,
:guilabel:`Project` fields, and possibly @mention relevant people.
* Set all the relevant :ref:`labels <triage-labels>`.
* Where appropriate, set the :guilabel:`Assignees`, :guilabel:`Reviewers`, and
:guilabel:`Project` :ref:`fields <triage-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
---------
Expand All @@ -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

@ezio-melotti ezio-melotti Aug 12, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

experts list?

@StanFromIreland StanFromIreland Aug 12, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Renders as "Experts index" already:

image

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 <https://github.com/orgs/python/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 <gh-labels>` is added.


.. _helptriage:
Expand All @@ -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
<tracker>` and existing issues are being updated. Every issue needs to be
triaged to make sure everything runs smoothly.

Classifying reports
-------------------
Expand All @@ -63,23 +108,24 @@ 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.
* Write a unit test: if the bug lacks a unit test that should end up in
Python's test suite, having that written can be very helpful.

This is all helpful as it allows members of the :ref:`triage team <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
-----------------------
Expand All @@ -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 <news-entry>` (if needed)
* doesn't have conflicts with the ``main`` branch
* :ref:`doesn't have failing CI checks <keeping-ci-green>`

Doing all of this allows core developers and :ref:`triagers <triage-team>`
Doing all of this allows core team members and :ref:`triagers <triage-team>`
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
----------------------------------

Expand Down
Loading