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

PEP 581: Copy editing (GH-757)

This commit is contained in:
Harmon 2018-08-15 14:20:47 -05:00 committed by Mariatta
parent 4a33866e32
commit 45179d1991
1 changed files with 94 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

189
pep-0581.rst
View File

@ -3,7 +3,7 @@ Title: Using GitHub Issues for CPython
Version: $Revision$
Last-Modified: $Date$
Author: Mariatta Wijaya <mariatta@python.org>
Discussions-To: ``#pep581`` stream in zulip
Discussions-To: ``#pep581`` stream in Zulip
Status: Draft
Type: Process
Content-Type: text/x-rst
@ -14,69 +14,69 @@ Abstract
========
This PEP outlines the steps required to migrate Python's issue tracker
from Roundup to using GitHub Issues.
from Roundup to GitHub issues.
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 in bugs.python.org (bpo) [1]_.
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) [1]_.
Why GitHub
----------
GitHub has a lot of nice features readily available out of the box, that are not
currently available in Roundup / bpo.
GitHub has a lot of nice features, readily available out of the box, that are
not currently available on Roundup / bpo.
- APIs we can use to build integrations and automations. There are various existing
integrations and applications available from GitHub Marketplace to help with
our workflow. New applications are easily installed and enabled. In addition,
we've had great success with building our own GitHub bots, like miss-islington [14]_,
bedevere [15]_, and the-knights-who-say-ni [16]_.
- 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 [14]_, bedevere [15]_, and the-knights-who-say-ni [16]_.
- Ability to embed/drag and drop screenshots, debug log files into GitHub pull
requests and issues.
- 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.
- Administrators and core developers can edit issues, comments, and pull requests.
- Ability to reply to issues and pull request conversations via email.
- Ability to reply to issue and pull request conversations via email.
- It supports two factor authentication.
- Support for two factor authentication.
- It supports markdown and emoji.
- Support for markdown and emoji.
- It has a preview tab, so we can see how our comment will be rendered, before
- Preview tab, showing how a comment will be rendered, prior to
actually posting.
- It supports voting (reactions).
- Support for voting via reactions.
- It supports permalink [2]_, allowing us to quote and copy paste
source code easily.
- Support for permalinks [2]_, 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.
- We can automatically close issues when a PR has been merged [3]_.
- Ability to automatically close issues when a PR has been merged [3]_.
- Lowers the barrier to contribution. With more than 28 million users, an open
source contributor is more likely to already have an account, and familiar
with GitHub interface, making it easier to start contributing.
- 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 contain metadata [4]_, integrated with GMail, and
allows you to systematically filter emails.
- Email notifications containing metadata [4]_, integrated with Gmail, allowing
systematic filtering of emails.
- Provides additional privacy such as offering the user a choice to hide an
email address yet still allow communication with the user through @-mentions.
- 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 bpo / Roundup
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 existing
(few) maintainers in terms of reviewing, testing, and applying patches.
- 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.
@ -84,7 +84,7 @@ Issues with bpo / Roundup
- The upstream Roundup is in Mercurial. There is an open discussion about
moving the source code of bpo to GitHub [5]_. 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 be difficult to maintain
upstream. But as long as it is in Mercurial, it is difficult to maintain
and onboard new contributors.
- The user interface needs update and redesign. It will require UX/UI research
@ -95,14 +95,14 @@ Issues with bpo / Roundup
- There is no REST API available. There is an open issue in Roundup for adding
REST API [6]_. 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 we get
email notification whenever someone added themselves as "nosy".
- 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 [7]_.
- Creating an account has been a hassle. We've had reports when people have
trouble creating accounts or logging in.
- Creating an account has been a hassle. There have been reports of people
having trouble creating accounts or logging in.
Why not GitLab
--------------
@ -110,16 +110,16 @@ 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 other issue tracker
---------------------------
Why not another issue tracker
-----------------------------
Using another issue tracker will require yet another learning curve, of having
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, where
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, and not having to jump from one interface to another.
contributors and maintainers, while not having to jump from one interface to another.
Why not focus on improving Roundup / bpo
----------------------------------------
@ -128,14 +128,14 @@ 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,
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
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.
is much less than the effort needed to get Roundup up to speed and then to
continue maintaining it.
Migration Plan
@ -144,34 +144,33 @@ Migration Plan
Backup of GitHub data
---------------------
This effort has been started and being tracked as an issue in core-workflow
[8]_. We're using GitHub Migrations API [9]_
to download GitHub data for CPython on daily basis. The archives will be
dropped in an S3 bucket.
This effort has been started and is being tracked as an issue in core-workflow
[8]_. We're using GitHub's Migrations API [9]_ 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
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
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.
Currently the CLA process involves real human to manually check the records.
Currently, the CLA process requires personnel to manually check the records.
Question: Will it be possible to completely automate the CLA process, so
it does not require human intervention?
Create labels for issue triage
------------------------------
In bpo, we currently have the following fields for each issues:
In bpo, we currently have the following fields for each issue:
Type: behavior, crash, compile error, resource usage, security, performance, enhancement.
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
@ -183,7 +182,7 @@ We will create the corresponding labels::
priority-release blocker, priority-deferred blocker, priority-critical, ...
In addition, we'll create ``needs triage`` label.
In addition, we'll create a ``needs triage`` label.
Create issue templates
----------------------
@ -198,12 +197,12 @@ We will create an issue template and add the following headers::
---
The idea is to allow the issue creator to help us triage the issue.
The above values are pre-filled in the template. Issue creator will remove texts
that do not apply to their 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 issue creator did not supply the above headers, the bot will apply
``needs triage`` label. At that point it will require a core developer to
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.
@ -211,8 +210,8 @@ We can also take advantage of GitHub's multiple issue template feature.
Updates to bedevere
-------------------
Bedevere-bot will need to be updated to recognize the issue headers described above,
and apply the proper labels.
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.
@ -225,8 +224,8 @@ 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 actual update to the bpo. But I believe this effort needed
is much less than a complete overhaul.
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.
@ -238,52 +237,52 @@ just be closed.
If a core developer is still interested in the issue, they can indicate so in
the bpo issue, and later use the button to migrate it over to GitHub.
Make bpo readonly
-----------------
Make bpo read-only
------------------
This should be the final step. Once we start using GitHub issues, make bpo
readonly, not shut it down.
read-only, instead of shutting it down.
Do not accept new registrations. Do not allow comments or issues to be created.
TBD and additional concerns
===========================
Expert index
------------
Experts index
-------------
At the moment, there is a mechanism to add people in expert index automatically
added to the nosy list. We need to replicate this functionality.
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 it was discussed about moving the CPython codebase from Mercurial
to GitHub [10]_ and [11]_, it was brought up that
we need to still allow uploading patches in bpo, and that a GitHub account should
not be a requirement in order to contribute to Python.
Back when moving the CPython codebase from Mercurial to GitHub was being
discussed [10]_ [11]_, 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 readonly, we'll need to come up with a different solution to allow
folks to contribute when they don't own a GitHub account.
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
One solution is to create a new "python-issues" mailing list, similar to the
docs@python.org [12]_ mailing list, to allow people to submit their issues
there.
Related to this, since the migration to GitHub in 2017, I recall one case
[13]_ where we had one contributor who submitted patch to Mercurial, and
refused to create a GitHub account. Because of this, our bot is unable to detect
whether the have signed CLA. Another person had volunteered to upload his
patch to GitHub. But we still require both people to sign the CLA.
[13]_ 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
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 we shorten the list?
Can the list be shortened?
Priority list
-------------
@ -301,7 +300,7 @@ stream in python.zulipchat.com.
Acknowledgements
================
Thanks to Guido van Rossum, Brett Cannon, and Nick Coghlan who were consulted
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.
@ -313,7 +312,7 @@ References
(https://bugs.python.org/)
.. [2] Getting permanent links to files
https://help.github.com/articles/getting-permanent-links-to-files/
(https://help.github.com/articles/getting-permanent-links-to-files/)
.. [3] Closing issues using keywords
(https://help.github.com/articles/closing-issues-using-keywords/)
@ -323,19 +322,19 @@ References
.. [5] Consider whether or not to migrate bugs.python.org source code
to GitHub repo
https://github.com/python/bugs.python.org/issues/2
(https://github.com/python/bugs.python.org/issues/2)
.. [6] Roundup issue 2550734 Expose roundup via a RESTful interface
.. [6] Roundup issue 2550734: Expose roundup via a RESTful interface
(http://issues.roundup-tracker.org/issue2550734)
.. [7] Roundup issue 2550742 Do not send email by default when adding
.. [7] Roundup issue 2550742: Do not send email by default when adding
or removing oneself from the Nosy list
(http://issues.roundup-tracker.org/issue2550742)
.. [8] Backup GitHub information
(https://github.com/python/core-workflow/issues/20)
.. [9] GitHub Migrations API
.. [9] GitHub's Migrations API
(https://developer.github.com/v3/migrations/orgs/)
.. [10] Python-committers email
@ -347,7 +346,7 @@ References
.. [12] docs mailing list
(https://mail.python.org/mailman/listinfo/docs)
.. [13] CPython GitHub Pull request 1505
.. [13] CPython GitHub pull request 1505
(https://github.com/python/cpython/pull/1505)
.. [14] miss-islington