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 2 commits into
base: main
Choose a base branch
from
+82 −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
2 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
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
134 changes: 77 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,31 @@
.. _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.

@encukou encukou Jul 30, 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.

Should this also mention old issue number format, e.g. that bpo-12345 means 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>`.
:github:`devguide repository <python/devguide>` instead.

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

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 +44,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 +62,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 +85,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 +118,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 +130,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
------------

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

Expand All @@ -134,6 +150,17 @@ 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, use a Markdown link with the path
of the file relative to the repository root, for example
``[the os module docs](Doc/library/os.rst)``. In issues, such links
point to the latest version of the file on the default branch. In PRs,
they are resolved against the PR's branch instead, so prefer permanent
links there.
Comment on lines +153 to +158

@hugovk hugovk Jul 30, 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.

I don't think we need to recommend this as the one way to do it, GH's default way is quite good.

Examples from this repo:

https://github.com/python/devguide/blob/main/testing/new-buildbot-worker.rst

Permalink version:

https://github.com/python/devguide/blob/137ada6ad31c46878e31d75f8b7e99e897f04c96/testing/new-buildbot-worker.rst

Linking to a permalink line gives a preview:

devguide/testing/new-buildbot-worker.rst

Line 38 in 137ada6

Preparing for buildbot worker setup

Or a code block for multiple lines:

devguide/testing/new-buildbot-worker.rst

Lines 38 to 44 in 137ada6

Preparing for buildbot worker setup
===================================
Since the goal is to build Python from source, the system will need to have
everything required to do normal python development: a compiler, a linker, and
(except on Windows) the "development" headers for any of the optional modules
(zlib, OpenSSL, and so on) supported by the platform. Follow the steps outlined in

@sirosen sirosen Jul 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Is it satisfactory to say "either use a permalink or ..."? Explaining permalinks, beyond the link out, seems likely to balloon the text and hurt readability.

I always ask for permalinks in other projects.

@hugovk hugovk Jul 30, 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.

It really depends on the context. If I say "please update this file" then the main one is just file.

But if I want to refer to something specific (like some code there right now then a permalink makes more sense.

I don't think we need to explain all this stuff. More words in the devguide means less of it will be read. And it's already big :)

@sirosen sirosen Jul 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Keeping it succinct is very difficult but a worthy goal.

As a full rephrase, what about this?

Links to files in the repository should either point to main or to a specific version of the file. In issues, a Markdown link with the path of the file relative to the repository root, for example [the os module docs](Doc/library/os.rst), will point to main.
Use permalinks to refer to exact lines in files.

@hugovk hugovk Jul 30, 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.

I'd just leave this paragraph out.


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>`__.


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

Expand All @@ -145,28 +172,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 +199,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 +228,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