Notice: While Javascript is not essential for this website, your interaction with the content will be limited. Please turn Javascript on for the full experience.

PEP 581 -- Using GitHub Issues for CPython

Title:Using GitHub Issues for CPython
Author:Mariatta Wijaya <mariatta at>
Discussions-To:#pep581 stream in Zulip


This PEP outlines the steps required to migrate Python's issue tracker from Roundup to GitHub issues.


CPython's development moved to GitHub on February 2017. All other projects within the PSF's organization are hosted on GitHub and are using GitHub issues. CPython is still using Roundup as the issue tracker on (bpo) [1].

Why GitHub

GitHub has a lot of nice features, readily available out of the box, that are not currently available on Roundup / bpo.

  • APIs that can be used to build integrations and automations. There are various existing integrations and applications available from GitHub Marketplace to help with the workflow. New applications are easily installed and enabled. In addition, we've had great success with building our own GitHub bots, like miss-islington [2], bedevere [3], and the-knights-who-say-ni [4].
  • Ability to embed/drag and drop screenshots and debug log files into GitHub pull requests and issues.
  • Administrators and core developers can edit issues, comments, and pull requests.
  • Ability to reply to issue and pull request conversations via email.
  • Support for two factor authentication.
  • Support for markdown and emoji.
  • Preview tab, showing how a comment will be rendered, prior to actually posting.
  • Support for voting via reactions.
  • Support for permalinks [5], allowing easy quoting and copying & pasting of source code.
  • Core developers don't have to maintain the issue infrastructure/site, giving us more time to focus on the development of Python.
  • Ability to automatically close issues when a PR has been merged [6].
  • Lower barrier to contribution. With more than 28 million users, an open source contributor is more likely to already have an account and be familiar with GitHub's interface, making it easier to start contributing.
  • Email notifications containing metadata [7], integrated with Gmail, allowing systematic filtering of emails.
  • Additional privacy, such as offering the user a choice to hide an email address, while still allowing communication with the user through @-mentions.

Issues with Roundup / bpo

  • Less than five people maintain bpo. Some of them are core developers.
  • It is in Mercurial. Without any CI available, it puts heavy burden on the few existing maintainers in terms of reviewing, testing, and applying patches.
  • At its current state, it is not equipped to accept lots of contributions from people who aren't already familiar with the code base.
  • The upstream Roundup is in Mercurial. There is an open discussion about moving the source code of bpo to GitHub [8]. If the source code of bpo does move to GitHub, it will become difficult to update patches from upstream. But as long as it is in Mercurial, it is difficult to maintain and onboard new contributors.
  • The user interface needs an update and redesign. It will require UX/UI research to keep it up to date with current web standards, including accessibility.
  • Email address is exposed. There is no choice to mask it.
  • There is no REST API available. There is an open issue in Roundup for adding REST API [9]. Last activity was in 2016.
  • It sends a number of unnecessary emails and notifications, and it is difficult, if not impossible, to configure. An example is the nosy email, where email notifications are sent whenever someone adds themselves as "nosy". An issue has been filed in upstream Roundup about this since 2012 with little traction [10].
  • Creating an account has been a hassle. There have been reports of people having trouble creating accounts or logging in.

Why not GitLab

Had we migrated to GitLab instead of GitHub in 2017, this PEP would have been titled "Using GitLab Issues for CPython".

Why not another issue tracker

Using another issue tracker will require yet another learning curve, for having to learn and get used to a different interface. We'll also need to learn and figure out how to build the integrations with GitHub.

By using GitHub issues, where the CPython source code is currently hosted and where pull requests are taking place, we'll be providing consistent experience to contributors and maintainers, while not having to jump from one interface to another.

Why not focus on improving Roundup / bpo

GitHub has many features we like that are already available. We still need to build out additional integrations and update our bots, but this is something we already know how to do.

In order to really improve Roundup / bpo, it needs to first migrate to GitHub and add CI and bots. As I understand it, there is hesitation because upstream Roundup is still in Mercurial. Someone more familiar with Roundup / bpo needs to champion this effort. (I'm not volunteering, I'm sorry).

I believe the effort of creating and maintaining GitHub integrations and bots is much less than the effort needed to get Roundup up to speed and then to continue maintaining it.

Migration Plan

Backup of GitHub data

This effort has been started and is being tracked as an issue in core-workflow [11]. We're using GitHub's Migrations API [12] to download GitHub data for CPython on a daily basis. The archives will be dropped in a S3 bucket.

Thanks to Ernest W. Durbin III for working on this.

Update the CLA host

At the moment, the CLA is hosted within bpo. It needs to be updated such that signing the CLA does not require a bpo account, and it should be hosted outside of the bpo.

The current CLA process itself is not ideal. Currently, contributors to devguide, peps, and core-workflow need to sign a CLA, and it requires a bpo account. A bpo account should not be required for those projects.

There is an ongoing effort to start using our own instance of CLA assistant instead of the current CLA process in place. Discussion about this has been started in core-workflow mailing list as well as on Discourse.

Create Bug Triage Team on GitHub

The bug triagers on bpo are valuable to the core Python workflow, and we definitely would need even more help with triaging issues on GitHub.

It has been proposed on Discourse for us to create a "bug triage" team on GitHub to help with closing issues, notifying the appropriate parties, as well as applying labels to issues and pull requests. We can grant the "write" permission to the "bug triage" team, while limiting merging pull requests to "CPython core developer" team on GitHub.

Create labels for issue triage

In bpo, we currently have the following fields for each issue:

Types: behavior, crash, compile error, resource usage, security, performance, enhancement. Components: 2to3, Argument Clinic, asyncio, Build, Cross-build, ctypes, ... Priority: release blocker, deferred blocker, critical, high, normal, low

We will create the corresponding labels:

type-behavior, type-crash, type-compile error, type-resource usage, ...

components-2to3, components-argument clinic, components-asyncio, ...

priority-release blocker, priority-deferred blocker, priority-critical, ...

In addition, we'll create a needs triage label.

The final "labels" to be created can be decided at a later time when it is time to start switching to GitHub issues.

Create issue templates

We will create an issue template and add the following headers:

Type: behavior | crash | compile error | resource usage (choose one)
Components: 2to3 | Argument Clinic | asyncio | Build | ... (can select more than one)
Priority: release blocker | deferred blocker | critical | ...
Needs backport to: 2.7 | 3.6 | 3.7

The idea is to allow the issue creator to help us triage the issue. The above values are pre-filled in the template. The issue creator will remove texts that do not apply to their issue.

Based on the above headers, bedevere-bot can apply the necessary labels to the issue. If the issue creator did not supply the above headers, the bot will apply the needs triage label. At that point, it will require a core developer to properly label the issue.

We can also take advantage of GitHub's multiple issue template feature, and the ability to automatically set issue assignee and labels by using issue templates.

Updates to bedevere

Bedevere-bot will need to be updated to recognize the issue headers described above and apply the proper labels.

Bedevere-bot can also copy over the labels to pull requests that correspond to the issue.

Update the devguide

Provide explanation in the devguide about new issue workflow and triage labels.

Add a button in bpo to migrate the issue to GitHub

This will require the bpo to be updated. But I believe the effort needed for this is much less than a complete overhaul.

We will create a button in bpo, that will copy over the issue description and associated comments into a GitHub issue.

We need to add a new status: "moved" with the url of the GitHub issue.

We should not be moving all open issues to GitHub. Only when someone is interested in continuing work or discussion about the issue, that the issue should be "moved" to GitHub.

Migrated issues

When an issue is marked as "moved", this issue should be in read-only mode. bpo should forbid edits to the issue.

Make bpo read-only

This should be the final step. Once we start using GitHub issues, make bpo read-only, instead of shutting it down. Do not accept new registrations. Do not allow new comments or issues.

Mapping between issues from bpo and GitHub

Usually when we reference an issue from bpo, we use bpo-XYZ but with Github, we will have a new reference with the format

Because we will migrate the issues from bpo to GitHub, we need to have a new field on bpo for the reference to the issues on GitHub, and the same thing on Github for the 'eventual' reference from bpo.

For GitHub, we need to add "origin:". For bpo, add a new field "moved to:"

TBD and additional concerns

Experts index

At the moment, there is a mechanism to automatically add people in the experts index to the nosy list. We need to replicate this functionality.

A GitHub account should not be a requirement

Back when moving the CPython codebase from Mercurial to GitHub was being discussed [13] [14], it was brought up that we still needed to allow uploading of patches on bpo, and that a GitHub account should not be a requirement in order to contribute to Python.

If bpo is made read-only, we'll need to come up with a different solution to allow people to contribute when they don't have a GitHub account.

One solution is to create a new "python-issues" mailing list, similar to the [15] mailing list, to allow people to submit their issues there.

Related to this, since the migration to GitHub in 2017, I recall one case [16] where there was a contributor, who submitted a patch to Mercurial and refused to create a GitHub account. Because of this, our bot was unable to detect whether they had signed the CLA. Another person had volunteered to upload their patch to GitHub. But it was still required that both people sign the CLA.

That particular situation was complicated. It took up five core developers' time to investigate and manually check the CLA, causing confusion.

Trim off the "Components" list

Is the current "components" list still making sense and relevant? Can the list be shortened?

Priority list

Is the current "priority" list useful? Nick Coghlan noted that perhaps only release blocker and deferred blocker are useful.

Further questions and discussions

There is a dedicated #pep581 stream in


Thanks to Guido van Rossum, Brett Cannon, and Nick Coghlan, who were consulted in the early stage and research of this PEP. Their feedback, concerns, input, and ideas have been valuable.


[1] (
[2]miss-islington (
[3]bedevere (
[4]the-knights-who-say-ni (
[5]Getting permanent links to files (
[6]Closing issues using keywords (
[7]About GitHub email notifications (
[8]Consider whether or not to migrate source code to GitHub repo (
[9]Roundup issue 2550734: Expose roundup via a RESTful interface (
[10]Roundup issue 2550742: Do not send email by default when adding or removing oneself from the Nosy list (
[11]Backup GitHub information (
[12]GitHub's Migrations API (
[13]Python-committers email (
[14]Python-committers email (
[15]docs mailing list (
[16]CPython GitHub pull request 1505 (