iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Split GitHub migration rationale and plan into two separate PEPs (#1013)

This commit is contained in:
Barry Warsaw 2019-04-30 16:51:45 -07:00 committed by Mariatta
parent 969ccb255e
commit b393d4bbfd
2 changed files with 314 additions and 244 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

287
pep-0581.rst
View File

@ -3,6 +3,7 @@ Title: Using GitHub Issues for CPython
Version: $Revision$
Last-Modified: $Date$
Author: Mariatta Wijaya <mariatta@python.org>
BDFL-Delegate: Barry Warsaw <barry@python.org>
Discussions-To: ``#pep581`` stream in Zulip
Status: Draft
Type: Process
@ -14,19 +15,22 @@ Post-History: 7-Mar-2019
Abstract
========
This PEP outlines the steps required to migrate Python's issue tracker
from Roundup to GitHub issues.
This PEP outlines the rationale for migration from Python's issue
tracker on Roundup to GitHub issues. See PEP 588 for the detailed
migration plan.
Rationale
=========
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 bugs.python.org (bpo) [#]_.
CPython's development moved to GitHub in 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 bugs.python.org (bpo) [#]_.
Why GitHub
----------
Why GitHub?
-----------
GitHub has a lot of nice features, readily available out of the box, that are
not currently available on Roundup / bpo.
@ -56,8 +60,9 @@ not currently available on Roundup / bpo.
- Support for permalinks [#]_, 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.
- Core developers, volunteers, and the PSF don't have to maintain the
issue infrastructure/site, giving us more time and resources to focus on the
development of Python.
- Ability to automatically close issues when a PR has been merged [#]_.
@ -69,29 +74,33 @@ not currently available on Roundup / bpo.
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.
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.
- The upstream Roundup code 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.
There is an open discussion about moving the source code of bpo to
GitHub [#]_. 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 upstream Roundup is in Mercurial. There is an open discussion about
moving the source code of bpo to GitHub [#]_. 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.
- In its current state, the project is not equipped to accept lots of
contributions from people who aren't already familiar with the code
base.
- 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.
- Users email addresses are exposed. There is no option to mask it.
- There is no REST API available. There is an open issue in Roundup for adding
REST API [#]_. Last activity was in 2016.
@ -105,25 +114,29 @@ Issues with Roundup / bpo
- Creating an account has been a hassle. There have been reports of people
having trouble creating accounts or logging in.
Why not GitLab
--------------
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
-----------------------------
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.
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
----------------------------------------
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
@ -139,200 +152,12 @@ 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
[#]_. 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.
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 <https://mail.python.org/archives/list/core-workflow@python.org/thread/JBV3XJVD2DLDX5DY7TZEA6CO5YPNHJ2C/>`_ as
well as on `Discourse <https://discuss.python.org/t/using-cla-assistant-for-python/990>`_.
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 <https://discuss.python.org/t/proposal-create-bug-triage-team-on-github/992/5>`_
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 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"
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 [#]_ [#]_, 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
docs@python.org [#]_ mailing list, to allow people to submit their issues
there.
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.
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 <https://python.zulipchat.com/#narrow/stream/130206-pep581>`_
stream in python.zulipchat.com.
There is a dedicated `#pep581
<https://python.zulipchat.com/#narrow/stream/130206-pep581>`_ stream
in python.zulipchat.com.
Acknowledgements
@ -378,24 +203,6 @@ References
or removing oneself from the Nosy list
(http://issues.roundup-tracker.org/issue2550742)
.. [#] 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)
Copyright
=========
@ -406,7 +213,7 @@ This document has been placed in the public domain.
..
Local Variables:
mode: indented-text
mode: rst
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70

271
pep-0588.rst
View File

@ -1,6 +1,7 @@
PEP: 588
Title: Reserved
Author: Barry Warsaw <barry@python.org>, Mariatta <mariatta@python.org>
Title: GitHub Issues Migration Plan
Author: Mariatta <mariatta@python.org>
BDFL-Delegate: Barry Warsaw <barry@python.org>
Status: Draft
Type: Informational
Content-Type: text/x-rst
@ -10,7 +11,269 @@ Created: 27-Mar-2019
Abstract
========
This PEP is reserved for near future use. Contact the authors for details.
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.
Migration Plan
==============
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.
Backup of GitHub data
---------------------
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.
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
<https://mail.python.org/archives/list/core-workflow@python.org/thread/JBV3XJVD2DLDX5DY7TZEA6CO5YPNHJ2C/>`_
as well as on `Discourse
<https://discuss.python.org/t/using-cla-assistant-for-python/990>`_.
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
<https://discuss.python.org/t/proposal-create-bug-triage-team-on-github/992/5>`_
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 the edition of 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 comments or issues to be created.
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 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``.
Open issues
===========
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 [#]_ [#]_, 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
docs@python.org [#]_ mailing list, to allow people to submit their issues
there.
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.
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
<https://python.zulipchat.com/#narrow/stream/130206-pep581>`_ stream
in python.zulipchat.com.
Acknowledgements
================
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.
References
==========
.. [#] 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)
Copyright
@ -21,7 +284,7 @@ This document has been placed in the public domain.
..
Local Variables:
mode: indented-text
mode: rst
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70