PEP 581 Updates (#1114)

- include recent changes to bpo
- clarify the downsides of GitHub

pep-0581.rst

@@ -33,8 +33,8 @@ tracker on bugs.python.org (bpo) [#]_.
 Why GitHub?
 -----------
 
-GitHub has a lot of nice features, readily available out of the box, that are
+GitHub has a lot of nice features, readily available out of the box. Some of
-not currently available on Roundup / bpo.
+these aren't readily 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
@@ -59,7 +59,8 @@ not currently available on Roundup / bpo.
 - Support for voting via reactions.
 
 - Support for permalinks [#]_, allowing easy quoting and copying & pasting of
-  source code.
+  source code. It is possible to automatically embed code snippet on GitHub
+  by pasting a permalink.
 
 - 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
@@ -67,12 +68,15 @@ not currently available on Roundup / bpo.
 
 - Ability to automatically close issues when a PR has been merged [#]_.
 
+  - Note: This ability been added to bpo after PEP 581's acceptance.
+
 - 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.
+  systematic filtering of emails. While Roundup emails contain some metadata,
+  they're not as extensive.
 
 - Additional privacy, such as offering the user a choice to hide an
   email address, while still allowing communication with the user
@@ -86,7 +90,9 @@ Issues with Roundup / bpo
 
 - 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.
+  reviewing, testing, and applying patches. While there is an unofficial mirror
+  of Roundup on GitHub [#]_, Mercurial patches are still the main way to contribute
+  to it.
 
   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
@@ -101,19 +107,27 @@ Issues with Roundup / bpo
 - 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.
+- Users email addresses were exposed.
 
-- There is no REST API available. There is an open issue in Roundup for adding
+  - Note: Exposing email address to registered and logged in users was a decision
-  REST API  [#]_. Last activity was in 2016.
+    taken when bpo instance was setup. This behavior has been recently modified
+    after PEP 581's acceptance.
 
-- It sends a number of unnecessary emails and notifications, and it is
+- REST API is not currently available in bpo. There was an open issue in Roundup
-  difficult, if not impossible, to configure. An example is the nosy email,
+  for adding REST API  [#]_. At the time PEP 581 was proposed, the ticket received
+  no activity since 2016. REST API has been integrated in Roundup in February 2019,
+  however it is not yet integrated to bpo.
+
+- It sends a number of unnecessary emails and notifications. 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 [#]_.
+  little traction [#]_. While it can be configured, the request to configure it
+  was not addressed/ignored.
 
 - Creating an account has been a hassle. There have been reports of people
-  having trouble creating accounts or logging in.
+  having trouble creating accounts or logging in. Some examples of open tickets:
+  "Commas in username causes error in nosy list" [#]_, "An error has occurred .." [#]_,
+  "It is not sending me the confirmation email ..." [#]_.
 
 
 Why not GitLab?
@@ -152,6 +166,50 @@ 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.
 
+Downsides of GitHub
+===================
+
+GitHub is not the perfect issue tracker. Several issues we need to be aware of:
+
+- Fear of uncertainty and vendor lock in. GitHub is proprietary and there is
+  risk of vendor lock-in. However, this is an existing problem since CPython's
+  codebase is already on GitHub. This is also not a unique problem to CPython.
+  As a precautionary step, CPython's repository on GitHub has
+  been backed up on daily basis since June 2018. [#]_
+
+- Bots maintenance costs money, and also takes up volunteer time. We would
+  be shifting maintenance burden from Roundup to the bots. At the very least,
+  so far we've been able to address any bugs/issues related to the bots/GitHub
+  APIs rather quickly, in a matter of days, instead of months or years. GitHub
+  APIs are extensive, and used not only by CPython's bots but also by the wider
+  Python community. It makes GitHub APIs more approachable compared to
+  the maintenance of Roundup/bpo.
+
+- Using GitHub could possibly increase the triaging effort. This was first raised
+  as a Zulip topic [#]_, and also brought up during Core Python sprint in
+  September 2018 [#]_. A few solutions have been proposed and considered, such as
+  creating a special triage team [#]_.  After PEP 581's acceptance, GitHub released a
+  new triaging role, currently in beta. The PSF has been in touch with GitHub
+  to have this enabled for Python organization. This is pending GitHub's review [#]_.
+
+- Using GitHub could make it easier for people to post disruptive or spammy comments.
+  It is true that there has been incidents where core developers have to moderate
+  and lock disruptive discussions on GitHub. Thankfully, GitHub interface makes
+  it easy for core developers to moderate discussions. In addition, incidents
+  can be escalated to GitHub.
+
+- Manually editing issue templates can be cumbersome and error-prone. However,
+  for most people, creating issues on GitHub will be a much better experience
+  than creating issue on bpo. The numerous fields and textbox to choose from
+  can be confusing and intimidating to a newcomer, and it is not possible
+  to "edit" a message. On GitHub, issue creator can preview their submission,
+  and edit their mistake after posting.
+
+- bpo uses a number of fields to specify several metadata, and these might not
+  be easily transferable to GitHub. The intended way to handle custom metadata
+  on GitHub is by using labels. The details of which labels to create will be
+  further discussed in PEP 588.
+
 
 Further questions and discussions
 =================================
@@ -193,6 +251,9 @@ References
 .. [#] About GitHub email notifications
    (https://help.github.com/articles/about-email-notifications/)
 
+.. [#] Unofficial GitHub mirror of Roundup
+   (https://github.com/roundup-tracker/roundup)
+
 .. [#] Consider whether or not to migrate bugs.python.org source code
    to GitHub repo
    (https://github.com/python/bugs.python.org/issues/2)
@@ -204,6 +265,30 @@ References
    or removing oneself from the Nosy list
    (http://issues.roundup-tracker.org/issue2550742)
 
+.. [#] Commas in username causes error
+   (https://github.com/python/bugs.python.org/issues/26)
+
+.. [#] It is not sending me the confirmation email
+   (https://github.com/python/bugs.python.org/issues/27)
+
+.. [#] An error has occurred
+   (https://github.com/python/bugs.python.org/issues/26)
+
+.. [#] s/n ratio -- Python -- Zulip
+   (https://python.zulipchat.com/#narrow/stream/130206-pep581/topic/s.2Fn.20ratio)
+
+.. [#] Backup GitHub information
+   (https://github.com/python/core-workflow/issues/20#issuecomment-396709762)
+
+.. [#] PEP 581 discussion at Python Core Sprint 2018
+   (https://mariatta.ca/core-sprint-2018-part-2.html)
+
+.. [#] Proposal: Create Bug Triage team on GitHub
+   (https://discuss.python.org/t/proposal-create-bug-triage-team-on-github/992)
+
+.. [#] Request to enable triage role on GitHub
+   (https://discuss.python.org/t/proposal-create-bug-triage-team-on-github/992/16)
+
 
 Copyright
 =========