11. 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.

11.1. 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.
  • Messages
  • History

11.1.1. Title

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.

11.1.2. Type

Describes the type of issue. If an issue does not fit within any specific type, please do not set a type.

Type Description
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.

11.1.3. Stage

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.

Stage Description
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).

11.1.4. Components

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 Submit changes.

One or more components may be selected for an issue:

Component Description
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/).
email 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.

11.1.5. Versions

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.

11.1.6. Priority

What is the severity and urgency?

Priority Description
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.

11.1.7. Keywords

Various informational flags about the issue. Multiple values are possible.

Keyword Description
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.
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.

11.1.8. Nosy List

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 Experts Index to know who wants to be added to the nosy list for issues targeting specific areas.

If you are logged in and have JavaScript enabled, you can use the [+] 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 Experts Index. 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.

11.1.9. Assigned To

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 Experts Index 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 Developer role on the issue tracker.

11.1.10. Dependencies

The issue requires the listed issue(s) to be resolved first before it can move forward.

11.1.11. Superseder

The issue is a duplicate of the listed issue(s).

11.1.12. Status

Status Description
open Issue is not resolved.

The issue is blocked until someone (often the OP) 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).

11.1.13. Resolution

Why the issue is in its current state. This is not usually used for issues with the “open” status.

Resolution Description
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.

11.1.14. Mercurial Repository

HTTP link to a Mercurial repository that contains a patch for the issue. A 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.

11.3. 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.
    • Type
    • Stage
    • Components: multiple items may be set
    • Versions: set if known, leave blank if unsure. Multiple items may be set.
  • Review and set process fields
    • Status
    • Resolution
    • Superseder
    • Assigned To
    • Nosy List
    • Priority
    • Keywords
  • (Optional) Leave a brief comment about the proposed next action needed. If there is a long message list, a summary can be very helpful.