Triaging Python tickets

Welcome! This page contains instructions for triaging Python tickets, which is something anyone can do and is a great way to get started with contributing to Python.

This page focuses on 3 types of triage: verifying bugs, reviewing patches, and reviewing documentation patches.

Overview

This section of the CPython developer guide details triaging tickets. Please note that any registered user can comment on a ticket, but one must have "Developer" rights on the issue tracker to update certain ticket fields.

If you don't have Developer rights, don't worry! Leave detailed comments on a ticket, and everyone on the nosy list will get an email. With your triage comments, you've greatly increased the chance that someone will move the ticket forward.

Also, if you do this for a while, you'll get Developer rights so you can make the ticket field changes yourself!

Verifying bugs

Often, someone will report a bug, but nobody will want to work on a patch for it until the bug is confirmed. Thus, confirming a bug is a big step towards getting it fixed.

Bug verification checklist

If you can reproduce the bug:

Say that you can reproduce the bug.
Reiterate what you expected to happen, and what actually happened.
Enumerate the steps you took to reproduce the problem. Do at least one of:
1. include a complete transcript, including the commands you ran, Python code you entered at the interpreter, tracebacks, etc. If the output is very long, for readability, attach it to the ticket instead of putting it directly in the comment.
2. Attach a short, standalone program that reproduces the bug to the ticket. This will be a helpful basis for writing test cases.
List all versions of Python in which the bug was and wasn't present for you.
List all operating systems on which the bug was and wasn't present for you.

If you can't reproduce the bug:

Say that you can't reproduce the bug.
Enumerate the steps you took to try and reproduce the problem.
List all versions of Python in which the bug wasn't present for you.
List all operating systems on which the bug wasn't present for you.

Example review

jesstess, thanks for your bug report!

I was able to reproduce the issue on both the default branch and in Python 3.4. I couldn't reproduce on 3.3, so this looks like a regression. I tested on OSX 10.8.4 but I believe this bug exists on all operating systems.

I've attached a short script as a reproducer. The expected output is for it to print 42, but it raises a ValueError.

Reviewing patches

CPython committers are really busy, and they typically won't try to merge a patch until someone else has reviewed it. Thus, reviewing a patch is a big step towards getting it merged.

Patch review checklist

In your review, answer these questions:

Does the patch apply cleanly?
Does the patch make sense, and implement the solution in a straightforward way?
If a bug fix, does the patch fix the problem it says it does? Two ways to assess this are:
1. If the bug has a reproducer, verify that the reproducer doesn't fail with the patch applied.
2. If the patch includes tests, verify that the tests fail with the code changes reverted.
Does make patchcheck pass?
Is the patch accompanied by new tests that either exercise the bug or the new functionality?
Do the tests impacted by the patch still pass? (The committer will run the whole test suite, but you can run just the relevant tests)
If functionality was added or changed, is the patch accompanied by new or updated documentation?

Example patch review

jesstess, thanks for your patch and tests!

The docstring for parse_request needs to be updated as part of this change.

Other than that, the patch looks correct from my inspection, applies cleanly, and implements a straightforward solution.

I verified that with the patch applied, the reproducer no longer raises a ValueError and instead prints 42 as expected. make patchcheck also reports no errors, and the test_httplib tests still pass. I confirmed that the tests for parsing unicode strings that were added in this patch exercise the bug, as they fail with the code changes reverted and pass with the full patch applied.

After the docstring is updated, I think this is ready for a commit review!

Reviewing documentation patches

Documentation patches have some different steps from code patches. They don't generally require accompanying tests, and they should be inspected visually for correctness.

Documentation patch review checklist

In your review, answer these questions:

Does the patch apply cleanly?
Is the documentation change correct, succinct, spelling error free, and grammatically correct?
Does make patchcheck pass?
Does the documentation build without errors? In general, building just the HTML docs is sufficient.
Does the resulting HTML look reasonable? (For example: is the code formatted correctly, do the footnote links work)

Example documentation review

jesstess, thanks for your patch!

The docs build cleanly with the patch. I visually inspected the changes in the built HTML docs and they look good. I also ran the modified example code from the docs and confirmed that it runs as expected.
I think this is ready for a commit review!

Finding tickets to triage

Bug reports that need verifying are typically in the "needs patch" stage.

Patches that need review are typically in the "patch review" stage.

Documentation tickets are typically in the "Documentation" component.