python-peps/pep-0581.rst

PEP: 581
Title: Using GitHub Issues for CPython
Version: $Revision$
Last-Modified: $Date$
Author: Mariatta <mariatta@python.org>
BDFL-Delegate: Barry Warsaw <barry@python.org>
Discussions-To: ``#pep581`` stream in Zulip
Status: Draft
Type: Process
Content-Type: text/x-rst
Created: 20-Jun-2018
Post-History: 7-Mar-2019


Abstract
========

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 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?
-----------

GitHub has a lot of nice features, readily available out of the box, that are
not currently available on Roundup / bpo.

- 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 [#]_, bedevere [#]_, and the-knights-who-say-ni [#]_.

- 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.

- Ability to reply to issue and pull request conversations via email.

- Support for two factor authentication.

- Support for markdown and emoji.

- Preview tab, showing how a comment will be rendered, prior to
  actually posting.

- Support for voting via reactions.

- Support for permalinks [#]_, allowing easy quoting and copying & pasting of
  source code.

- 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 [#]_.

- 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 containing metadata [#]_, integrated with Gmail, allowing
  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.


Issues with Roundup / bpo
-------------------------

- Less than five people maintain bpo. Some of them are core developers.

- 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.

  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.

- 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.

- 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 [#]_.

- Creating an account has been a hassle. There have been reports of people
  having trouble creating accounts or logging in.


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?
==============================

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.


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
we already know how to do.

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.


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
==========

.. [#] bugs.python.org
   (https://bugs.python.org/)

.. [#] miss-islington
   (https://github.com/python/miss-islington)

.. [#] bedevere
   (https://github.com/python/bedevere)

.. [#] the-knights-who-say-ni
   (https://github.com/python/the-knights-who-say-ni)

.. [#] Getting permanent links to files
   (https://help.github.com/articles/getting-permanent-links-to-files/)

.. [#] Closing issues using keywords
   (https://help.github.com/articles/closing-issues-using-keywords/)

.. [#] About GitHub email notifications
   (https://help.github.com/articles/about-email-notifications/)

.. [#] Consider whether or not to migrate bugs.python.org source code
   to GitHub repo
   (https://github.com/python/bugs.python.org/issues/2)

.. [#] Roundup issue 2550734: Expose roundup via a RESTful interface
   (http://issues.roundup-tracker.org/issue2550734)

.. [#] Roundup issue 2550742: Do not send email by default when adding
   or removing oneself from the Nosy list
   (http://issues.roundup-tracker.org/issue2550742)


Copyright
=========

This document has been placed in the public domain.



..
   Local Variables:
   mode: rst
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 70
   coding: utf-8
   End: