Triagers, core developers and bots can add labels on GitHub to categorize issues and pull requests. Many labels are shared for both use cases, while some are dedicated only to one. Below is a possibly inexhaustive list, but it should get you going. For a full list, see here.
These labels are used to specify the type of issue:
- :gh-label:`type-bug`: for unexpected behaviors, bugs, or exceptions (not hard crashes).
- :gh-label:`type-crash`: for hard crashes of the interpreter, possibly with a core dump.
- :gh-label:`type-feature`: for feature requests or enhancements.
Feature requests do not need :ref:`version labels <Version labels>`;
it is implicit that features are added to the
mainbranch only, except for some :ref:`exceptional cases <exceptional-version-labels>`. The Ideas Discourse category can be used to discuss enhancements before filing an issue. - :gh-label:`type-security`: for security issues. See also Reporting security issues in Python.
These labels are mostly used to specify which :ref:`part of the codebase <build-directory-structure>` is affected by the issue/PR:
- :gh-label:`stdlib`: for standard library modules in the :cpy-file:`Lib` directory (written in Python).
- :gh-label:`extension-modules`: for standard library modules in the :cpy-file:`Modules` directory (written in C).
- :gh-label:`interpreter-core`: for changes related to the interpreter core in the :cpy-file:`Objects`, :cpy-file:`Python`, :cpy-file:`Grammar`, and :cpy-file:`Parser` dirs (written mostly in C).
- :gh-label:`docs`: for documentation in the :cpy-file:`Doc` directory (written in :ref:`reStructuredText <markup>`), docstrings, and code comments.
- :gh-label:`tests`: for tests in the :cpy-file:`Lib/test` directory (written in Python) and other changes related to tests, :mod:`unittest`, or :mod:`doctest`.
These labels are used to specify which operating systems are affected. Since most issues either affect all systems or are specific to Unix, we don't have a dedicated Unix label. Use :gh-label:`OS-windows`, :gh-label:`OS-mac`, and :gh-label:`OS-freebsd`.
Use the :gh-label:`OS-unsupported` label for issues on platforms outside the support tiers defined in PEP 11. Applying this label adds the issue to a GitHub project where it can be categorized further. See also the :ref:`Platform experts list <platform-experts>`.
These labels are used to denote the specific topic area, if any, of the issue/PR. This includes both specific modules/packages and generic interest areas.
Adding these labels is also a way to notify the relevant experts, since they are encouraged to subscribe to them. Depending on the label, this might also automatically add the issue to a GitHub project.
You can see the full list of topic labels on GitHub.
These labels are used to indicate which versions of Python are affected. The available version labels (with the form :samp:`3.{N}`) are updated whenever new feature releases are created or retired.
- For security issues, add the :gh-label:`type-security` label and the affected version labels. This makes the issue stand out.
- For non-security issues affecting all bugfix branches, only add the :gh-label:`type-bug` label as knowing which versions are affected does not give more information.
- Labels for end-of-life versions should be removed when possible but there is no need to explicitly go through old issues to remove such labels.
- Otherwise, add the corresponding version labels and remember to update them when the latest major version is updated.
See also :ref:`the branch status page <branchstatus>` for a list of active branches.
While features should not have a version label, there are a few exceptional cases subject to the release manager approval:
If we are currently in the beta period of :samp:`3.{N}.0` and if a feature was implemented in its alpha period but requires a non-trivial extension (hence a new feature issue), this new feature issue is given the :samp:`3.{N}` label as the latest version under development would now be :samp:`3.{N+1}.0a1`.
To indicate that the labelling is correct and the extension is approved, the :gh-label:`triaged` label can also be applied.
- :gh-label:`build`/:gh-label:`performance`: for issues related to the build process or performance, respectively.
- :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:`pending`: for issues/PRs that will be closed unless further feedback is provided.
- :gh-label:`release-blocker`/:gh-label:`deferred-blocker`: for issues/PRs and the :ref:`branch's release manager <branchstatus>` removing or retaining the label as appropriate. that, unless fixed, will hold the current or next release respectively. Triagers may set these labels for issues that must be fixed before a release, will review them and determine if they indeed qualify,
- :gh-label:`sprint`: for easier filtering of issues/PRs being worked on during official sprints.
- :gh-label:`stale`: for issues/PRs that have been inactive for a while.
- :gh-label:`triaged`: for issue has been accepted as valid by a triager.
The following labels only apply to :ref:`Pull Requests <pullrequest>`. They are either set automatically by bots, or added by humans to trigger specific bot behaviors.
- :gh-label:`DO-NOT-MERGE`: for PRs that shouldn't be merged in their current state. It also prevents miss-islington from being able to automatically merge the PR.
- :samp:`needs backport to {X.Y}`: used to indicate which branches the PR
should be backported to. Once the PR is merged,
miss-islingtonwill automatically attempt to create backport PRs for the versions indicated by these labels. See also :ref:`the status of the Python branches <branchstatus>` for a list of branches and the type of PRs that can be backported to them. - :gh-label:`skip issue <skip%20issue>`: for trivial changes (such as typo fixes, comment changes, and section rephrases) that don't require a corresponding issue.
- :gh-label:`skip news <skip%20news>`: for PRs that don't need a NEWS entry. The :ref:`news-entry` section covers in details in which cases the NEWS entry can be skipped.
- :gh-label:`test-with-buildbots`: used to test the latest commit with the :ref:`buildbot fleet <buildbots>` whenever more testing is required before merging. This may take multiple hours to complete.
- :samp:`awaiting {action}`: these labels are applied and used by bedevere to indicate the stage of a PR and should not be applied manually.