diff --git a/pep-0595.rst b/pep-0595.rst new file mode 100644 index 000000000..e0c124b6a --- /dev/null +++ b/pep-0595.rst @@ -0,0 +1,470 @@ +PEP: 595 +Title: Improving bugs.python.org +Author: Ezio Melotti , Berker Peksag +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 " 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: