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