python-peps/pep-0595.rst

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: