|Title:||GitHub Issues Migration Plan|
|Author:||Mariatta <mariatta at python.org>|
|BDFL-Delegate:||Barry Warsaw <barry at python.org>|
- Migration Plan
- Open issues
- Further questions and discussions
This PEP describes the detailed plan for migrating from Python's issue tracker on Roundup to GitHub issues. See PEP 581 for rationale and background. PEP 588 also describes the detailed timeline for the migration.
Here we outline the tasks, steps, and core decisions we need to make in order to migrate bug tracking to GitHub, with the least impact on CPython developer productivity.
This effort has been started and is being tracked as an issue in core-workflow . We're using GitHub's Migrations API  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.
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.
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.
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.
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.
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.
Provide explanation in the devguide about new issue workflow and triage labels.
When an issue is marked as "moved", this issue should be in read-only mode. bpo should forbid the edition of the issue.
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 comments or issues to be created.
Usually when we reference an issue from bpo, we use bpo-XYZ but with Github, we will have a new reference with this format https://github.com/python/cpython/issue/XYZ.
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: https://bugs.python.org/issueXYZ. For bpo, add a new field moved to: https://github.com/python/cpython/issue/XYZ.
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.
Back when moving the CPython codebase from Mercurial to GitHub was being discussed  , 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.
Related to this, since the migration to GitHub in 2017, I recall one case  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.
Is the current "components" list still making sense and relevant? Can the list be shortened?
Is the current "priority" list useful? Nick Coghlan noted that perhaps only release blocker and deferred blocker are useful.
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.
|||Backup GitHub information (https://github.com/python/core-workflow/issues/20)|
|||GitHub's Migrations API (https://developer.github.com/v3/migrations/orgs/)|
|||Python-committers email (https://mail.python.org/pipermail/python-committers/2015-December/003642.html)|
|||Python-committers email (https://mail.python.org/pipermail/python-committers/2015-December/003645.html)|
|||docs mailing list (https://mail.python.org/mailman/listinfo/docs)|
|||CPython GitHub pull request 1505 (https://github.com/python/cpython/pull/1505)|
This document has been placed in the public domain.