PEP 595: Improving bugs.python.org (#1083)
* Add my initial draft * PEP 593: update PEP structure and add content. * PEP 593: Push updates * PEP 593: expand the "Improving Roundup" section and move it to the top. * PEP 593: expand the "Roundup advantages" and "Migration considerations" sections. * PEP 595 (was 593): expand and reword some sections. * PEP 595: rename file * PEP 595: remove Discussion-To header, fix formatting of Author header.
This commit is contained in:
Ezio Melotti
GitHub
parent
eb6282b4a7
commit
17b1fc57fb
|
|
@ -0,0 +1,470 @@
|
||||||
|
PEP: 595
|
||||||
|
Title: Improving bugs.python.org
|
||||||
|
Author: Ezio Melotti <ezio.melotti@gmail.com>, Berker Peksag <berker.peksag@gmail.com>
|
||||||
|
Status: Draft
|
||||||
|
Type: Process
|
||||||
|
Content-Type: text/x-rst
|
||||||
|
Created: 12-May-2019
|
||||||
|
|
||||||
|
|
||||||
|
Abstract
|
||||||
|
========
|
||||||
|
|
||||||
|
This PEP proposes a list of improvements to make bugs.python.org
|
||||||
|
more usable for contributors and core developers. This PEP also
|
||||||
|
discusses why remaining on Roundup should be preferred over
|
||||||
|
switching to GitHub Issues, as proposed by :pep:`581`.
|
||||||
|
|
||||||
|
|
||||||
|
Motivation
|
||||||
|
==========
|
||||||
|
|
||||||
|
On May 14th, 2019 :pep:`581` has been accepted [#]_ without much
|
||||||
|
public discussion and without a clear consensus [#]_. The PEP
|
||||||
|
contains factual errors and doesn't address some of the
|
||||||
|
issues that the migration to GitHub Issues might present.
|
||||||
|
|
||||||
|
Given the scope of the migration, the amount of work required,
|
||||||
|
and how it will negatively affect the workflow during the
|
||||||
|
transition phase, this decision should be re-evaluated.
|
||||||
|
|
||||||
|
.. TODO: add a section with background and terminology?
|
||||||
|
(e.g. roundup, bpo, instances, github issues, pep581/588)
|
||||||
|
|
||||||
|
Roundup advantages over GitHub Issues
|
||||||
|
=====================================
|
||||||
|
|
||||||
|
This section discusses reasons why Roundup should be preferred
|
||||||
|
over GitHub Issues and Roundup features that are not available
|
||||||
|
on GitHub Issues.
|
||||||
|
|
||||||
|
* **Roundup is the status quo.** Roundup has been an integral
|
||||||
|
part of the CPython workflow for years. It is a stable product
|
||||||
|
that has been tested and customized to adapt to our needs as the
|
||||||
|
workflow evolved.
|
||||||
|
|
||||||
|
It is possible to gradually improve it and avoid the disruption
|
||||||
|
that a switch to a different system would inevitabily bring to
|
||||||
|
the workflow.
|
||||||
|
|
||||||
|
* **Open-source and Python powered.** Roundup is an open-source
|
||||||
|
project and is written in Python. By using it and supporting
|
||||||
|
it, we also support the Python ecosystem. Several features
|
||||||
|
developed for bpo have also been ported to upstream Roundup
|
||||||
|
over the years.
|
||||||
|
|
||||||
|
* **Fully customizable.** Roundup can be (and has been) fully
|
||||||
|
customized to fit our needs.
|
||||||
|
|
||||||
|
* **Finer-grained access control.** Roundup allows the creation
|
||||||
|
of different roles with different permissions (e.g. create,
|
||||||
|
view, edit, etc.) for each individual property, and users can
|
||||||
|
have multiple roles.
|
||||||
|
|
||||||
|
* **Flexible UI.** While Roundup UI might look dated, it is
|
||||||
|
convenient and flexible.
|
||||||
|
|
||||||
|
For example, on the issue page, each field (e.g. title, type,
|
||||||
|
versions, status, linked files and PRs, etc.) have appropriate
|
||||||
|
UI elements (input boxes, dropdowns, tables, etc.) that are
|
||||||
|
easy to set and also provide a convenient way to get info about
|
||||||
|
the issue at a glance. The number of fields, their values, and
|
||||||
|
the UI element they use is also fully customizable.
|
||||||
|
GitHub only provides labels.
|
||||||
|
|
||||||
|
The issue list page presents the issues in a compact and easy
|
||||||
|
to read table with separate columns for different fields. For
|
||||||
|
comparison, Roundup lists 50 issues in a screen, whereas GitHub
|
||||||
|
takes two screens to shows 25 issues.
|
||||||
|
|
||||||
|
* **Advanced search.** Roundup provides an accurate way to search
|
||||||
|
and filter by using any combination of issue fields.
|
||||||
|
It is also possible to customize the number of results and the
|
||||||
|
fields displayed in the table, and the sorting and grouping
|
||||||
|
(up to two levels).
|
||||||
|
|
||||||
|
bpo also provides predefined summaries (e.g. "Created by you",
|
||||||
|
"Assigned to you", etc.) and allows the creation of custom
|
||||||
|
search queries that can be conveniently accessed from the sidebar.
|
||||||
|
|
||||||
|
* **Nosy list autocomplete.** The nosy list has an autocomplete
|
||||||
|
feature that suggests maintainers and experts. The suggestions
|
||||||
|
are automatically updated when the experts index [#]_ changes.
|
||||||
|
|
||||||
|
* **Dependencies and Superseders.** Roundup allows to specify
|
||||||
|
dependencies that must be addressed before the current issues
|
||||||
|
can be closed and a superseder issue to easily mark duplicates
|
||||||
|
[#]_. The list of dependencies can also be used to create
|
||||||
|
meta-issues that references several other sub-issues [#]_.
|
||||||
|
|
||||||
|
|
||||||
|
Improving Roundup
|
||||||
|
=================
|
||||||
|
|
||||||
|
This section lists some of the issues mentioned by :pep:`581`
|
||||||
|
and other desired features and discusses how they can be implemented
|
||||||
|
by improving Roundup and/or our instance.
|
||||||
|
|
||||||
|
* **REST API support.** A REST API will make integration with other
|
||||||
|
services and the development of new tools and applications easiers.
|
||||||
|
|
||||||
|
Upstream Roundup now supports a REST API. Updating the tracker will
|
||||||
|
make the REST API available.
|
||||||
|
|
||||||
|
* **GitHub login support.** This will allow users to login
|
||||||
|
to bugs.python.org (bpo) without having to create a new account.
|
||||||
|
It will also solve issues with confirmation emails being marked
|
||||||
|
as spam, and provide two-factor authentication.
|
||||||
|
|
||||||
|
A patch to add this functionality is already available and is
|
||||||
|
being integrated at the time of writing [#]_.
|
||||||
|
|
||||||
|
* **Markdown support and message preview and editing.** This feature
|
||||||
|
will allow the use of Markdown in messages and the ability to
|
||||||
|
preview the message before the submission and edit it afterward.
|
||||||
|
|
||||||
|
This can be done, but it will take some work. Possible solutions
|
||||||
|
have been proposed on the roundup-devel mailing list [#]_.
|
||||||
|
|
||||||
|
* **"Remove me from nosy list" button.** Add a button on issue pages
|
||||||
|
to remove self from the nosy list.
|
||||||
|
|
||||||
|
This feature will be added during GSoC 2019.
|
||||||
|
|
||||||
|
* **Mobile friendly theme.** Current theme of bugs.python.org looks
|
||||||
|
dated and it doesn't work well with mobile browsers.
|
||||||
|
|
||||||
|
A mobile-friendly theme that is more modern but still familiar
|
||||||
|
will be added.
|
||||||
|
|
||||||
|
* **Add PR link to BPO emails.** Currently bpo emails don't include
|
||||||
|
links to the corresponding PRs.
|
||||||
|
|
||||||
|
A patch [#]_ is available to change the content of the bpo emails
|
||||||
|
from::
|
||||||
|
|
||||||
|
components: +Tkinter
|
||||||
|
versions: +Python 3.4
|
||||||
|
pull_requests: +42
|
||||||
|
|
||||||
|
to::
|
||||||
|
|
||||||
|
components: +Tkinter
|
||||||
|
versions: +Python 3.4
|
||||||
|
pull_request: https://github.com/python/cpython/pull/341
|
||||||
|
|
||||||
|
* **Python 3 support.** Using Python 3 will make maintenance easier.
|
||||||
|
|
||||||
|
Upstream Roundup now supports Python 3. Updating the tracker will
|
||||||
|
allow us to switch to Python 3. The instances will need to be
|
||||||
|
updated as well.
|
||||||
|
|
||||||
|
* **Use upstream Roundup.** We currently use a fork of Roundup with
|
||||||
|
a few modifications, most notably the GitHub integration. If this
|
||||||
|
is ported upstream, we can start using upstream Roundup without
|
||||||
|
having to maintain our fork.
|
||||||
|
|
||||||
|
|
||||||
|
PEP 581 issues
|
||||||
|
==============
|
||||||
|
|
||||||
|
This section addresses some errors and inaccuracies found in :pep:`581`.
|
||||||
|
|
||||||
|
The "Why GitHub?" section of PEP 581 lists features currently
|
||||||
|
available on GitHub Issues but not on Roundup. Some of this features
|
||||||
|
are currently supported:
|
||||||
|
|
||||||
|
* "Ability to reply to issue and pull request conversations via email."
|
||||||
|
|
||||||
|
* Being able to reply by email has been one of the core features of
|
||||||
|
Roundup since the beginning. It is also possible to create new
|
||||||
|
issues or close existing ones, set or modify fields, and add
|
||||||
|
attachments.
|
||||||
|
|
||||||
|
* "Email notifications containing metadata, integrated with Gmail,
|
||||||
|
allowing systematic filtering of emails."
|
||||||
|
|
||||||
|
* Emails sent by Roundup contains metadata that can be used for
|
||||||
|
filtering.
|
||||||
|
|
||||||
|
* "Additional privacy, such as offering the user a choice to hide an
|
||||||
|
email address, while still allowing communication with the user
|
||||||
|
through @-mentions."
|
||||||
|
|
||||||
|
* Email addresses are hidden by default to users that are not
|
||||||
|
registered. Registered users can see other users' addresses
|
||||||
|
because we configured the tracker to show them. It can easily
|
||||||
|
be changed if desired. Users can still be added to the nosy
|
||||||
|
list by using their username even if their address is hidden.
|
||||||
|
|
||||||
|
* "Ability to automatically close issues when a PR has been merged."
|
||||||
|
|
||||||
|
* The GitHub integration of Roundup automatically closes issues
|
||||||
|
when a commit that contains "fixes issue <id>" is merged.
|
||||||
|
(Alternative spellings such as "closes" or "bug" are also supported.)
|
||||||
|
See [#]_ for a recent example of this feature.
|
||||||
|
|
||||||
|
* "Support for permalinks, allowing easy quoting and copying &
|
||||||
|
pasting of source code."
|
||||||
|
|
||||||
|
* Roundup has permalinks for issues, messages, attachments, etc.
|
||||||
|
In addition, Roundup allows to easily rewrite broken URLs in
|
||||||
|
messages (e.g. if the code hosting changes).
|
||||||
|
|
||||||
|
* "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."
|
||||||
|
|
||||||
|
* While this is partially true, additional resources are required to
|
||||||
|
write and maintain bots.
|
||||||
|
|
||||||
|
In some cases, bots are required to workaround GitHub's lack of
|
||||||
|
features rather than expanding. [#]_ was written
|
||||||
|
specifically to workaround GitHub's email integration.
|
||||||
|
|
||||||
|
Updating our bots to stay up-to-date with changes in the GitHub API
|
||||||
|
has also maintenance cost. [#]_ took two days to be fixed.
|
||||||
|
|
||||||
|
In addition, we will still need to maintain Roundup for bpo (even
|
||||||
|
if it becomes read-only) and for the other trackers
|
||||||
|
we currently host/maintain (Jython [#]_ and Roundup [#]_).
|
||||||
|
|
||||||
|
The "Issues with Roundup / bpo" section of :pep:`581` lists some issues
|
||||||
|
that have already been fixed:
|
||||||
|
|
||||||
|
* "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."
|
||||||
|
|
||||||
|
* While Roundup uses Mercurial by default, there is a git clone
|
||||||
|
available on GitHub [#]_. Roundup also has CI available [#]_ [#]_.
|
||||||
|
|
||||||
|
* "There is no REST API available. There is an open issue in Roundup for
|
||||||
|
adding REST API. Last activity was in 2016."
|
||||||
|
|
||||||
|
* The REST API has been integrated and it's now available in Roundup.
|
||||||
|
|
||||||
|
* "Users email addresses are exposed. There is no option to mask it."
|
||||||
|
|
||||||
|
* Exposing addresses to registered and logged in users was a decision
|
||||||
|
taken when our instance was set up.
|
||||||
|
|
||||||
|
This has now been changed to make the email addresses hidden for
|
||||||
|
regular users too (Developers and Coordinators can still see them).
|
||||||
|
The "Email address"" column from the user listing page [#]_ has been
|
||||||
|
removed too.
|
||||||
|
|
||||||
|
* "It sends a number of unnecessary emails and notifications, and it is
|
||||||
|
difficult, if not impossible, to configure."
|
||||||
|
|
||||||
|
* This can be configured.
|
||||||
|
|
||||||
|
* "Creating an account has been a hassle. There have been reports of people
|
||||||
|
having trouble creating accounts or logging in."
|
||||||
|
|
||||||
|
* The main issue is confirmation emails being marked as spam. Work has
|
||||||
|
been done to resolve the issue.
|
||||||
|
|
||||||
|
.. TODO: investigate the status of this; when was the last report?
|
||||||
|
See https://mail.python.org/pipermail/tracker-discuss/2018-December/004631.html
|
||||||
|
|
||||||
|
|
||||||
|
Migration considerations
|
||||||
|
========================
|
||||||
|
|
||||||
|
This section describes issues with the migrations that might not
|
||||||
|
have been addressed by :pep:`581` and :pep:`588`.
|
||||||
|
|
||||||
|
:pep:`588` suggests to add a button to migrate issues to GitHub
|
||||||
|
only when someone wants to keep working on them. This approach
|
||||||
|
has several issues:
|
||||||
|
|
||||||
|
* bpo will need to be updated in order to add a button that,
|
||||||
|
once pressed, creates a new issue on GitHub, copies over all
|
||||||
|
the messages, attachments, and creates/adds label for the
|
||||||
|
existing fields. Permissions will also need to be tweaked
|
||||||
|
to make individual issues read-only once they are migrated,
|
||||||
|
and to prevent users to create new accounts.
|
||||||
|
|
||||||
|
* The issues will be split between two trackers; searching issues
|
||||||
|
will take significant more effort.
|
||||||
|
|
||||||
|
* The conversion from Roundup to GitHub is lossy, unless all
|
||||||
|
the bpo fields are converted into labels or preserved somewhere
|
||||||
|
else.
|
||||||
|
|
||||||
|
* bpo converts a number of references into links, including
|
||||||
|
issue, message, and PR IDs, changeset numbers, legacy SVN
|
||||||
|
revision numbers, paths to files in the repo, files in
|
||||||
|
tracebacks (detecting the correct branch), links to devguide
|
||||||
|
pages and sections [#]_. This happens when messages are
|
||||||
|
requested so it is possible to create the correct link (e.g.
|
||||||
|
all the file links used to point to hg.python.org and now
|
||||||
|
point to GitHub).
|
||||||
|
|
||||||
|
If the links are hardcoded during the migration, it will be
|
||||||
|
difficult (if not impossible) to change them later. If they
|
||||||
|
aren't, they will either be lost, or a tool to generate the
|
||||||
|
links and updating them will need to be written.
|
||||||
|
|
||||||
|
* GitHub doesn't provide a way to set and preserve issue IDs
|
||||||
|
if they are migrated automatically with the use of a button.
|
||||||
|
(Some projects managed to preserve the IDs by contaacting
|
||||||
|
the GitHub staff and migrating the issues *en masse*.)
|
||||||
|
|
||||||
|
* On top of the work and changes required to migrate to GitHub
|
||||||
|
issues, we will still need to keep running and maintaining
|
||||||
|
Roundup, for both our instance (read-only) and for the Jython
|
||||||
|
and Roundup trackers (read-write).
|
||||||
|
|
||||||
|
|
||||||
|
In addition to the issues listed in the "Open issues" section of
|
||||||
|
:pep:`588`, this issues will need to be addressed:
|
||||||
|
|
||||||
|
* GitHub is properietary and there is risk of vendor lock-in.
|
||||||
|
Their business model might change and they could shut down
|
||||||
|
altogether.
|
||||||
|
|
||||||
|
* Switching to GitHub Issues will likely increase the number of
|
||||||
|
invalid reports and increase the triaging effort. This concern
|
||||||
|
has been raised in the past in a Zulip topic [#]_.
|
||||||
|
|
||||||
|
There have been already cases where people posted comments on
|
||||||
|
PRs that required moderators to mark them as off-topic or
|
||||||
|
disruptive, delete them altogether, and even lock the
|
||||||
|
conversation [#]_.
|
||||||
|
|
||||||
|
* Roundup sends weekly reports to python-dev with a summary that
|
||||||
|
includes new issues, recent issues with no replies, recent
|
||||||
|
issues waiting for review, most discussed issues, closed issues,
|
||||||
|
and deltas for open/closed/total issue counts [#]_. The report
|
||||||
|
provides an easy way to keep track of the tracker activity and
|
||||||
|
to make sure that issues that require attention are noticed.
|
||||||
|
|
||||||
|
The data collect by the weekly report is also use to generate
|
||||||
|
statistics and graphs that can be used to gain new insights [#]_.
|
||||||
|
|
||||||
|
* There are currently two mailing lists where Roundup posts new
|
||||||
|
tracker issues and all messages respectively: new-bugs-announce
|
||||||
|
[#]_ and python-bugs-list [#]_. A new system will need to be
|
||||||
|
developed to preserve this functionality. These MLs offer
|
||||||
|
additional ways to keep track of the tracker activity.
|
||||||
|
|
||||||
|
|
||||||
|
References
|
||||||
|
==========
|
||||||
|
|
||||||
|
.. [#] [Python-Dev] PEP 581 (Using GitHub issues for CPython) is accepted
|
||||||
|
|
||||||
|
https://mail.python.org/pipermail/python-dev/2019-May/157399.html
|
||||||
|
|
||||||
|
.. [#] [python-committers] [Python-Dev] PEP 581 (Using GitHub issues
|
||||||
|
for CPython) is accepted
|
||||||
|
|
||||||
|
https://mail.python.org/pipermail/python-committers/2019-May/006755.html
|
||||||
|
|
||||||
|
.. [#] Experts Index -- Python Devguide
|
||||||
|
|
||||||
|
https://devguide.python.org/experts/
|
||||||
|
|
||||||
|
.. [#] An example of superseded issues:
|
||||||
|
"re.sub() replaces only several matches"
|
||||||
|
|
||||||
|
https://bugs.python.org/issue12078
|
||||||
|
|
||||||
|
.. [#] An example of meta issue using dependencies to track sub-issues:
|
||||||
|
"Meta-issue: support of the android platform""
|
||||||
|
|
||||||
|
https://bugs.python.org/issue26865
|
||||||
|
|
||||||
|
.. [#] Support logging in with GitHub
|
||||||
|
|
||||||
|
https://github.com/python/bugs.python.org/issues/7
|
||||||
|
|
||||||
|
.. [#] Re: [Roundup-devel] PEP 581 and Google Summer of Code
|
||||||
|
|
||||||
|
https://sourceforge.net/p/roundup/mailman/message/36667828/
|
||||||
|
|
||||||
|
.. [#] [Tracker-discuss] [issue624] bpo emails contain useless non-github
|
||||||
|
pull_request number - users want a link to actual github PR
|
||||||
|
|
||||||
|
https://mail.python.org/pipermail/tracker-discuss/2018-June/004547.html
|
||||||
|
|
||||||
|
.. [#] The commit reported in msg342882 closes the issue (see the history below)
|
||||||
|
|
||||||
|
https://bugs.python.org/issue36951#msg342882
|
||||||
|
|
||||||
|
.. [#] The cpython-emailer-webhook project
|
||||||
|
|
||||||
|
https://github.com/berkerpeksag/cpython-emailer-webhook
|
||||||
|
|
||||||
|
.. [#] A recent incident caused by GitHub
|
||||||
|
|
||||||
|
https://github.com/python/bedevere/pull/163
|
||||||
|
|
||||||
|
.. [#] Jython issue tracker
|
||||||
|
|
||||||
|
https://bugs.jython.org/
|
||||||
|
|
||||||
|
.. [#] Roundup issue tracker
|
||||||
|
|
||||||
|
https://issues.roundup-tracker.org/
|
||||||
|
|
||||||
|
.. [#] GitHub clone of Roundup
|
||||||
|
|
||||||
|
https://github.com/roundup-tracker/roundup
|
||||||
|
|
||||||
|
.. [#] Travis-CI for Roundup
|
||||||
|
|
||||||
|
https://travis-ci.org/roundup-tracker/roundup) and codecov
|
||||||
|
|
||||||
|
.. [#] Codecov for Roundup
|
||||||
|
|
||||||
|
https://codecov.io/gh/roundup-tracker/roundup/commits
|
||||||
|
|
||||||
|
.. [#] User listing -- Python tracker
|
||||||
|
|
||||||
|
https://bugs.python.org/user?@sort=username
|
||||||
|
|
||||||
|
.. [#] Generating Special Links in a Comment -- Python Devguide
|
||||||
|
|
||||||
|
https://devguide.python.org/triaging/#generating-special-links-in-a-comment
|
||||||
|
|
||||||
|
.. [#] The New-bugs-announce mailing list
|
||||||
|
|
||||||
|
https://mail.python.org/mailman/listinfo/new-bugs-announce
|
||||||
|
|
||||||
|
.. [#] The Python-bugs-list mailing list
|
||||||
|
|
||||||
|
https://mail.python.org/mailman/listinfo/python-bugs-list
|
||||||
|
|
||||||
|
.. [#] An example of [Python-Dev] Summary of Python tracker Issues
|
||||||
|
|
||||||
|
https://mail.python.org/pipermail/python-dev/2019-May/157483.html
|
||||||
|
|
||||||
|
.. [#] Issues stats -- Python tracker
|
||||||
|
|
||||||
|
https://bugs.python.org/issue?@template=stats
|
||||||
|
|
||||||
|
.. [#] s/n ratio -- Python -- Zulip
|
||||||
|
|
||||||
|
https://python.zulipchat.com/#narrow/stream/130206-pep581/topic/s.2Fn.20ratio
|
||||||
|
|
||||||
|
.. [#] For example this and other related PRs:
|
||||||
|
|
||||||
|
https://github.com/python/cpython/pull/9099
|
||||||
|
|
||||||
|
|
||||||
|
Copyright
|
||||||
|
=========
|
||||||
|
|
||||||
|
This document has been placed in the public domain.
|
||||||
|
|
||||||
|
..
|
||||||
|
Local Variables:
|
||||||
|
mode: indented-text
|
||||||
|
indent-tabs-mode: nil
|
||||||
|
sentence-end-double-space: t
|
||||||
|
fill-column: 70
|
||||||
|
coding: utf-8
|
||||||
|
End:
|
||||||
Loading…
Reference in New Issue