Skip to content

Reorganize 'Using the issue tracker' (previously 'Issue tracker') #1854

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
StanFromIreland wants to merge 3 commits into
base: main
Choose a base branch
from
+78 −66
Open

Reorganize 'Using the issue tracker' (previously 'Issue tracker') #1854

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5690215
Reorganize 'Using the issue tracker' (previously 'Issue tracker')
StanFromIreland Jul 4, 2026
6130cc3
Expand section on links
StanFromIreland Jul 29, 2026
0fd0512
Hugo and Petr's reviews
StanFromIreland Jul 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,6 @@ contributors through the process.
* :ref:`helptriage`
* :ref:`experts`
* :ref:`labels`
* :ref:`gh-faq`
* :ref:`triage-team`

We **recommend** that sections of this guide be read as needed. You
Expand Down
130 changes: 73 additions & 57 deletions triage/issue-tracker.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,31 +1,33 @@
.. _issue-tracker:
.. _tracker:

=============
Issue tracker
=============

=======================
Using the issue tracker
=======================

The `issue tracker`_ is hosted on GitHub, alongside the codebase and pull requests.

.. note::

Prior to moving the issue tracker to GitHub,
Python used to use a dedicated `Roundup`_ instance as its issue tracker.
That `old bug tracker`_ was hosted under the domain ``bugs.python.org``
(sometimes called :dfn:`bpo` or :dfn:`BPO` for short). A read-only version is
available on that domain for historical purposes. All ``bpo`` data has been
migrated to the current issue tracker on GitHub.
Comment thread
StanFromIreland marked this conversation as resolved.
Old issues are still referenced in the :samp:`bpo-{NNN}` format,
where ``bpo-12345`` refers to ``https://bugs.python.org/issue12345``.


Reporting an issue
==================

If you think you have found a bug in Python, you can report it to the
`issue tracker`_. The `issue tracker`_ is now hosted on GitHub, alongside
the codebase and pull requests. Documentation bugs can also be reported there.
`issue tracker`_. Documentation bugs can also be reported there.

If you would like to file an issue about this devguide, please do so in the
:github:`devguide repository <python/devguide>`.

.. note::
Prior to moving the issue tracker to GitHub,
Python used to use a dedicated `Roundup`_ instance as its issue tracker.
That `old bug tracker`_ was hosted under the domain ``bugs.python.org``
(sometimes called ``bpo`` for short). A read-only version is
available on that domain for historical purposes. All ``bpo`` data has been
migrated to the current `issue tracker`_ on GitHub.
:github:`devguide repository <python/devguide>` instead.

If you're familiar with ``bpo`` and would like to learn more about GitHub
issues, please read this page, and the :ref:`triaging` page as they
provide good introductory material.

Checking if a bug already exists
--------------------------------
Expand All @@ -44,18 +46,9 @@ To see if an issue already exists, search the bug database using the search box
above the list of bugs on the issues page. See :ref:`searching-gh-issues`
for more information.

.. _searching-gh-issues:

How to search issues?
---------------------

Use the `GitHub search syntax`_ or the interactive `advanced search`_ form
that generates search queries for you.

Reporting an issue
------------------

.. XXX: This section is slightly out of date after recent tracker changes.
Creating a new issue
--------------------

If the problem you're reporting is not already in the `issue tracker`_, you
can report it using the green :guilabel:`New issue` button on the right of the search
Expand All @@ -71,14 +64,15 @@ available choices include, for example:
* **Report a security vulnerability**: privately report a security vulnerability.

Depending on your choice, a dedicated form template will appear.
In particular, you'll notice that the last button actually takes you to
In particular, you'll notice that one of the buttons actually takes you to
the `Python Discourse`_ (``discuss.python.org``),
where many Python-related discussions take place.

The submission form has only two fields that you need to fill:

* in the **Title** field, enter a *very* short description of the problem;
less than ten words is good;
less than ten words is good; don't include "labels" like ``[feature]``
as we use GitHub labels;
* in the **Write** field, describe the problem in detail using hints from
the template that was put in that field for you. Be sure to include what
you expected to happen, what did happen, and how to replicate the
Expand All @@ -93,10 +87,31 @@ Use the :ref:`experts` to know who wants to be
tagged or assigned for specific areas.

There are a number of additional fields like **Assignees**, **Labels**,
and **Projects**. Those are filled by triagers and core
developers and are covered in the :ref:`triaging` page. You don't need
and **Projects**. Those are filled by triagers and core team members
and are covered in the :ref:`triaging` page. You don't need
to worry about those when reporting issues as a Python user.


Working with issues
===================

This section covers common tasks on the issue tracker, such as
searching, commenting on, and following issues.

.. _searching-gh-issues:

Searching issues
----------------

Use the `GitHub search syntax`_ or the interactive `advanced search`_ form
that generates search queries for you.

You can also narrow down the results by filtering by label, either with
the :guilabel:`Labels` dropdown above the list of issues or with the
:samp:`label:{name}` search qualifier. See :ref:`gh-labels` for an
overview of the labels used in the CPython repository.


Formatting issues and comments
------------------------------

Expand All @@ -105,8 +120,9 @@ There is a wonderful `beginner guide to writing and formatting on GitHub
Highly recommended.

One pro-tip we can sell you right here is that if you want to paste
some longer log as a comment, attach a file instead (see how below).
If you still insist on pasting it in your comment, do it like this::
some longer log as a comment, :ref:`attach a file instead <attaching-to-gh-issues>`.
If you still insist on pasting it in your comment, wrap it with a
`collapsed section`_ using ``<details></details>`` for better readability::

<details>
<summary>This is the summary text, click me to expand</summary>
Expand All @@ -116,15 +132,17 @@ If you still insist on pasting it in your comment, do it like this::
</details>


How to attach files to an issue?
--------------------------------
.. _attaching-to-gh-issues:

Attaching files
---------------

Drag them into the comment field, wait until the file uploads, and GitHub
will automatically put a link to your file in your comment text.


Adding special links
--------------------
Adding links
------------
Comment on lines -126 to +145

@hugovk hugovk Jul 31, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For all these renamed headers, let's add .. _adding-special-links: and so on to retain the old anchors.


The following abbreviations can be used in a comment to generate a link:

Expand All @@ -134,6 +152,11 @@ The following abbreviations can be used in a comment to generate a link:

See also the `list of autolinks supported by GitHub <autolinks_>`_.

To link to a file in the repository, you can get a permanent link to a
given revision of the file by `pressing "y"
<https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files>`__.


Following issues
----------------

Expand All @@ -145,28 +168,19 @@ button in the sidebar. Note that you are automatically subscribed to
issues you create or comment on.


How to link to file paths in the repository when writing comments?
------------------------------------------------------------------

Use Markdown links. If you link to the default GitHub path, the file
will link to the latest current version on the given branch.

You can get a permanent link to a given revision of a given file by
`pressing "y" <https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files>`__.

Tracking dependencies and duplicates
------------------------------------

.. XXX These no longer work, the feature has been retired.

It is possible to use `checklists`_ to track dependencies or,
in case of meta-issues, to link to the other related issues.
It is possible to `create relationships between issues <issue-rel_>`_ to track
dependencies and in case of meta-issues, to `add sub-issues <sub-issues_>`_
to link to the other related issues.

By writing :samp:`Duplicate of #{NNN}` in a comment, you can
`mark issues and PRs as duplicates <duplicates_>`_.

What on earth is a "mannequin"?
-------------------------------

Mannequin accounts
------------------

For old issues migrated to GitHub from bugs.python.org (BPO) where the authors or commenters
were not core team members, we opted not to link to their GitHub accounts
Expand All @@ -181,8 +195,8 @@ name in their BPO profile, we use that. Otherwise, their classic BPO
username is used instead.


Disagreement with a resolution on the issue tracker
===================================================
Disagreement with a resolution
==============================

As humans, we will have differences of opinions from time to time. First and
foremost, please be respectful that care, thought, and volunteer time went into
Expand Down Expand Up @@ -210,7 +224,9 @@ reason either as ``complete`` or ``not planned``.
.. _Roundup: https://www.roundup-tracker.org/
.. _Python Discourse: https://discuss.python.org/
.. _autolinks: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls
.. _checklists: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists
.. _collapsed section: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections
.. _duplicates: https://docs.github.com/en/issues/tracking-your-work-with-issues/administering-issues/marking-issues-or-pull-requests-as-a-duplicate
.. _issue-rel: https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/creating-issue-dependencies
.. _sub-issues: https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues
.. _Core Development Discourse category: https://discuss.python.org/c/core-dev/23
.. _old bug tracker: https://bugs.python.org/
13 changes: 5 additions & 8 deletions triage/triaging.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,8 @@ Checklist for triaging
:guilabel:`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.
* If the issue is clearly invalid (unrelated to CPython, duplicate, spam, and
so on), you can use GitHub's "Close as not planned" option.
Comment thread
StanFromIreland marked this conversation as resolved.

Assignees
---------
Expand All @@ -36,7 +36,7 @@ how to proceed. 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** be
a team member, likely a triager or a core developer.
have at least triage permissions in the repository.

.. The Assignees subsection was copied from the labels.rst page in #930.
For consistency, the other fields mentioned above should be documented too.
Expand Down Expand Up @@ -105,8 +105,5 @@ 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.

.. _advanced search: https://github.com/search/advanced
in modules for which you have a working knowledge. See :ref:`searching-gh-issues`
for more information.
Loading