Triaging an Issue
This section of the devguide documents the issue tracker for users and developers.
Contributors with the Developer role on the issue tracker can triage issues directly without any assistance.
Additionally, this section provides an overview of the Python triage team.
Python triage team
The Python triage team is a group dedicated towards improving workflow efficiency through thoughtful review and triage of open issues and pull requests. This helps contributors receive timely feedback and enables core developers to focus on reviewed items which reduces their workload. The expectations of this role expand upon the "Developer" role on the issue tracker. The responsibilities listed below are primarily centered around the Python GitHub repositories. This extends beyond CPython, and, as needed, to other repos such as devguide and core-workflow.
- PR/issue management
- Renaming PRs
- Reviewing PRs
- Assisting contributors
- Notifying appropriate core developers
- Applying appropriate labels to PRs/Issues
- Skip news
- Skip issue
- Good first issue
- Other categorizations
As triagers gain experience, they may have some intuition of when a PR should be closed. Triagers can recommend closing a PR, but the final decision must be made by a core developer. By having triagers and core developers work together, the author receives a careful consideration of their PR. This encourages future contributions, regardless of whether their PR is accepted or closed.
Triagers can make use of the
stale labels to suggest that a
PR may be suitable for closure. For more information, see the
:ref:`GitHub PR labels <github-pr-labels>` section.
It is also of paramount importance to treat every contributor to the Python project kindly and with respect. Regardless of whether they're entirely new or a veteran core developer, they're actively choosing to voluntarily donate their time towards the improvement of Python. As is the case with any member of the Python Software Foundation, always follow the PSF Code of Conduct.
Becoming a member of the Python triage team
Any Python core developers are welcome to invite a Python contributor to the Python triage team. Do note that the responsibilities of a Python triager is more elevated than a developer on bpo. For example, the Python triager has access to more repositories than just CPython. Triagers will be responsible to handle not just issues, but also pull requests, and even managing backports.
Any existing developers on b.p.o can transition into becoming a Python triager. They can request this to any core developer, and the core developer can pass the request to the Python organization admin on GitHub. The request can be made confidentially via a DM in Zulip or Discourse, or publicly by opening an issue in the core-workflow repository.
Any contributor who is not already a developer on b.p.o can also self-nominate to be a member of Python triage team. They can request this to any core developer, confidentially via DM in Zulip or Discourse, or publicly by opening an issue in core-workflow. If a core developer agrees and is willing to vouch for them, the core developer can pass the request to the GitHub administrator. They should also be added as developer on bpo.
For every new triager, it would be great to announce them in the python-committers mailing list and core-workflow category in Discourse. Example announcement.
GitHub Labels for PRs
An important component of triaging PRs for the CPython repo involves appropriately categorizing them through the usage of labels.
Labels for PRs include:
- Used on PRs to prevent miss-islington from being able to automatically merge to pull request. This label is appropriate when a PR has a non-trivial conflict with the branch it is being merged into.
- Used for PRs which involve changes to the asyncio module or other asynchronous frameworks that utilize it.
- Used manually for PRs that do not meet basic requirements and automatically added by bedevere when PR authors attempt to merge maintenace branches into the master branch. During events such as the October Hacktoberfest, this label will prevent the PR from counting toward the author's contributions.
- needs backport to X.Y
- Used for PRs which are appropriate to backport to branches prior to master. Generally, backports to the maintenance branches are primarily bugfixes and documentation clarifications. Backports to the security branches are strictly reserved for PRs involving security fixes, such as crashes, privilege escalation, and DoS. The use of this label will cause miss-islington to attempt to automatically merge the PR into the branches specified.
- Used for PRs involving changes which only have an effect upon a specific operating system. Current variations of the label include OS-Windows and OS-Mac.
- skip issue
- Used for PRs which involve trivial changes, such as typo fixes, comment changes, and section rephrases. The majority of PRs require an issue to be attached to, but if there are no code changes and the section being modified retains the same meaning, this label might be appropriate.
- skip news
- Similar to the skip issue label, this label is used for PRs which involve trivial changes, backports, or already have a relevant news entry in another PR. Any potentially impactful changes should have a corresponding news entry, but for trivial changes it's commonly at the discretion of the PR author if they wish to opt-out of making one.
- Used for PRs authored during an in-person sprint, such as at PyCon, EuroPython, or other official Python events. The label is used to prioritize the review of those PRs during the sprint.
- Used for PRs that include changes which are no longer relevant or when the author hasn't responded to feedback in a long period of time. This label helps core developers quickly identify PRs that are candidates for closure or require a ping to the author.
- Used for PRs that address unintentional behavior, but do not pose significant security concerns. Generally, bugfixes will be attached to a specific issue where the unintended behavior was first reported.
- Used for PRs that exclusively involve changes to the documentation. Documentation includes *.rst files, docstrings, and code comments.
- Used for PRs that provide additional functionality or capabilities beyond the existing specifications.
- Used for PRs that provide performance optimizations.
- Used for PRs that involve critical security issues. Less severe security concerns can instead use the type-bugfix label.
- Used for PRs that exclusively involve changes to the tests.
Fields in the Issue Tracker
The major elements found in an issue report include:
- Classification (including Title) - These fields categorize the issue. The fields include Title, Type, Stage, Components, and Version.
- Process - These fields indicate the state of the issue and its progress toward resolution. The fields are Status, Resolution, Dependencies, Superseder, Assigned To, Nosy List, Priority, Keywords, Comment, File, File Description, Remote hg repo, GitHub PR.
A brief description of the issue. Review whether the title is too generic or specifies an incorrect term or library.
(Optional) Add a prefix at the start of the title to indicate the module, e.g. IDLE, doc, or asyncio.
Describes the type of issue. If an issue does not fit within any specific type, please do not set a type.
|behavior||Unexpected behavior, result, or exception. Most bugs will have this type.|
|compile error||Errors reported by the compiler while compiling Python.|
|crash||Hard crashes of the Python interpreter -- possibly with a core dump or a Windows error box.|
|enhancement||Issues that propose the addition of new functionality, such as new functions, classes, modules, or even new arguments for existing functions. Also used for improvements in the documentation, test suite and other refactorings. A good place to discuss enhancements prior to filing an issue is python-ideas mailing list.|
|performance||Situations where too much time is necessary to complete the task. For example, a common task now takes significantly longer to complete.|
|resource usage||Situations where too many resources (e.g. memory) are used.|
|security||Issues that might have security implications. Report security vulnerabilities using the procedure found in the Reporting security issues in Python page on the python.org website.|
A needed next action to advance the issue. The stage needn't be set until it is clear that the issue has been initially triaged and determined work will be needed.
|test needed||The steps which are needed to reproduce the issue. The bug reporter should post a script, instructions, or example to help someone test or reproduce the issue.|
|needs patch||A patch or pull request is needed to solve the problem (i.e. fixing the bug or adding the requested improvement).|
|patch review||A patch or pull request exists, but it needs review. Any triager or core developer may do the review.|
|commit review||A triager performed a patch review and it looks good. This signals to core developers the patch or pull request needs a quick once-over to make sure nothing was overlooked before committing it.|
|resolved||The issue is considered closed and addressed (e.g. patch or pull request committed; expected behavior).|
The area or Python library affected by the issue. This is a multi-select field.
Choosing certain components, such as Documentation, may cause the issue to
be auto-assigned, i.e. the issue tracker may automatically fill in the
Assigned To field after you press
One or more components may be selected for an issue:
|2to3 (2.x to 3 conversion tool)||The 2to3 conversion tool in Lib/lib2to3.|
|Build||The build process.|
|ctypes||The ctypes package in Lib/ctypes.|
|Demos and Tools||The files in Tools and Tools/demo.|
|Distutils||The distutils package in Lib/distutils.|
|Documentation||The documentation in Doc (source used to build HTML docs for https://docs.python.org/).|
|The email package and related modules.|
|Extension Modules||C modules in Modules.|
|IDLE||The Lib/idlelib package.|
|Installation||The installation process.|
|Interpreter Core||The interpreter core. The built-in objects in Objects, the Python, Grammar and Parser dirs.|
|IO||The I/O system, Lib/io.py and Modules/_io.|
|Library (Lib)||Python modules in Lib.|
|Macintosh||The Mac OS X operating system.|
|Regular Expressions||The Lib/re.py and Modules/_sre.c modules.|
|Tests||The unittest framework in Lib/unittest The doctest framework Lib/doctest.py. The CPython tests in Lib/test. The test runner in Lib/test/regrtest.py. The test support utilities in Lib/test/support.|
|Tkinter||The Lib/tkinter package.|
|Unicode||Unicode, codecs, str vs bytes, Objects/unicodeobject.c.|
|Windows||The Windows operating system.|
|XML||The Lib/xml package.|
The known versions of Python that the issue affects and should be fixed for.
Thus if an issue for a new feature is assigned for e.g., Python 3.8 but is not applied before Python 3.8.0 is released, this field should be updated to say Python 3.9 as the version and drop Python 3.8.
What is the severity and urgency?
|low||This is for low-impact bugs.|
|normal||The default value for most issues filed.|
|high||Try to fix the issue before the next final release.|
|critical||Should definitely be fixed for next final release.|
|deferred blocker||The issue will not hold up the next release, n. It will be promoted to a release blocker for the following release, n+1.|
|release blocker||The issue must be fixed before any release is made, e.g., will block the next release even if it is an alpha release.|
As a guideline, critical and above are usually reserved for crashes, serious regressions or breakage of very important APIs. Whether a bug is a release blocker for the current release schedule is decided by the release manager. Triagers may recommend this priority and should add the release manager to the nosy list. If needed, consult the release schedule and the release's associated PEP for the release manager's name.
Various informational flags about the issue. Multiple values are possible.
|buildbot||A buildbot triggered the issue being reported.|
|easy||Fixing the issue should not take longer than a day for someone new to contributing to Python to solve.|
|newcomer friendly||Issue suitable for newcomer/first time contributors. Not suitable for experienced contributors. Typically it is straightforward, well-defined, low-risk, and optionally someone is able to mentor the new contributor.|
|gsoc||The issue would fit as, or is related to, a GSoC project.|
|needs review||The patch or pull request attached to the issue is in need of a review.|
|patch||There is a patch or pull request attached to the issue.|
|3.3regression||The issue is a regression in 3.3.|
A list of people who may be interested in an issue.
It is acceptable to add someone to the nosy list if you think the issue should be brought to their attention. Use the :ref:`experts` to know who wants to be added to the nosy list for issues targeting specific areas.
button to add yourself to the nosy list (remember to click on
"Submit Changes" afterwards). Note that you are added to the nosy
automatically when you submit a message.
The nosy list also has an autocomplete that lets you search from the lists of developers and :ref:`experts`. The search is case-insensitive and works for real names, modules, interest areas, etc., and only adds the username(s) to the nosy once an entry is selected.
Who is expected to take the next step in resolving the issue.
It is acceptable to assign an issue to someone if the issue cannot move forward without their help, e.g., they need to make a technical decision to allow the issue to move forward. 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 have the :ref:`Developer role <devrole>` on the issue tracker.
The issue requires the listed issue(s) to be resolved first before it can move forward.
The issue is a duplicate of the listed issue(s).
|open||Issue is not resolved.|
The issue is blocked until someone (often the :abbr:`OP (original poster)`) provides some critical information; the issue will be closed after a set amount time if no reply comes in.
Useful when someone opens an issue that lacks enough information to reproduce the bug reported. Requesting additional information and setting status to pending indicates that the issue should be closed if the necessary information is not provided in a timely manner (i.e. one month).
|closed||The issue has been resolved (somehow).|
Why the issue is in its current state. This is not usually used for issues with the "open" status.
|open||Issue is not resolved.|
|duplicate||Duplicate of another issue; should have the Superseder field filled out.|
|fixed||A fix for the issue was committed.|
|later||Issue is to be worked on in a later release cycle.|
|not a bug||For some reason the issue is invalid (e.g. the perceived problem is not a bug in Python).|
|out of date||The issue has already been fixed, or the problem doesn't exist anymore for other reasons.|
|postponed||Issue will not be worked on at the moment but in a future minor release version.|
|rejected||Issue was rejected (especially for feature requests).|
|remind||The issue is acting as a reminder for someone.|
|wont fix||Issue will not be fixed, typically because it would cause a backwards-compatibility problem.|
|works for me||Bug cannot be reproduced.|
HTTP link to a Mercurial repository that contains a patch for the issue. A :guilabel:`Create Patch` button will appear that computes a diff for the head revision of the remote branch and attaches it to the issue. The button supports only CPython patches.
If you don't indicate a remote branch,
default is used. You can
indicate a remote branch by adding
#BRANCH to the end of the URL.
Generating Special Links in a Comment
Using the following abbreviations in a comment will automatically generate a link to relevant web pages.
||Links to the tracker issue
||Links to the tracker message
||Links to GitHub pull requests.|
|a 10-, 11-, 12-, or 40-digit hex
||Indicates a Git or Mercurial changeset identifier and
generates a link to changeset
||Indicates a legacy Subversion revision number,
a reference to a changeset that was checked in prior
to 2011-03-05 when the official Python source code
repositories were migrated from the
:abbr:`VCS (version control system)` to Mercurial.
The issue tracker automatically translates the legacy
||Links to files in the
Python source code repositories, possibly linking
to the line number specified after the
||Link to the :abbr:`PEP (Python Enhancement Proposal)`
||Links to the Devguide, this page, and this section respectively.|
Checklist for Triaging
- Read the issue comment(s).
- Review and set classification fields
- Title: should be concise with specifics which are helpful to someone scanning a list of issue titles. (Optional, if possible) Add a prefix at the start of the title to indicate the module, e.g. IDLE, doc, or async.
- Components: multiple items may be set
- Versions: set if known, leave blank if unsure. Multiple items may be set.
- Review and set process fields
- Assigned To
- Nosy List
- (Optional) Leave a brief comment about the proposed next action needed. If there is a long message list, a summary can be very helpful.