Important
This is part of a Draft of the Python Contributor’s Guide. Text in square brackets are notes about content to fill in. Currently, the devguide and this new Contributor’s Guide co-exist in the repo. We are using Sphinx include directives to demonstrate the re-organization. The final Contributor’s Guide will replace the devguide with content in only one place. We welcome help with this!
The [Plan for the Contributor’s Guide] page has more details about the current state of this draft and how you can help. See more info about the Contributor Guide in the discussion forum: Refactoring the DevGuide.
[This is the existing Triaging an issue page from the devguide]
Triaging an issue¶
This section of the devguide documents the issue tracker for users and developers.
Checklist for triaging¶
Read the initial message and the comments.
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 (
gh-NNNNN: Title
).Set all the relevant labels.
Where appropriate, set the Assignees, Reviewers, Project 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, etc), you can use GitHub’s “Close as not planned” option.
Assignees¶
This field indicates 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; for example, they need to make a technical decision on how to proceed. 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 be a team member, likely a triager or a core developer.
Helping triage issues¶
Once you know your way around how Python’s source files are 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 issue tracker and existing issues are being updated. Every issue needs to be triaged to make sure everything runs smoothly.
Classifying reports¶
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.
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.
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 triage team to properly classify an issue so it can be handled by the right core developers in a timely fashion.
Reviewing pull requests¶
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, Style guide, etc.)
includes proper tests
includes proper documentation changes
includes a NEWS entry (if needed)
includes the author in
Misc/ACKS
, either already or the pull request adds themdoesn’t have conflicts with the
main
branch
Doing all of this allows core developers and triagers to more quickly look for subtle issues that only people with extensive experience working on Python’s code base will notice.
See also Accepting pull requests.
Finding an issue you can help with¶
If you want to help with triaging, you might also want to search for issues in modules for which you have a working knowledge. Search for the name of a module in the issue tracker, filter by label, or use the advanced search to find these issues.