PEP 595: Improving bugs.python.org
Hello,
Berker and I have been working on a PEP that suggests we keep using
and improving bugs.python.org and Roundup instead of switching to
GitHub Issues as proposed by PEP 581.
The PEP covers:
* What are the advantages of Roundup over GitHub issues;
* What features are missing in Roundup and how can we add them;
* Issues with PEP 581;
* Issues with the migration plan proposed by PEP 588;
The rendered version of PEP 595 is available at
https://www.python.org/dev/peps/pep-0595/
For reference, you can consult PEP 581 and 588 at
https://www.python.org/dev/peps/pep-0581/ and
https://www.python.org/dev/peps/pep-0588/
The full text of the PEP is include below. We are planning to update
the PEP to include the feedback we receive and to update the status of
features as we implement them (we also have a Google Summer of Code
students working on it).
Best Regards,
Ezio Melotti
================
PEP: 595
Title: Improving bugs.python.org
Author: Ezio Melotti
-cc: committers to avoid crossposting. I have feedback for roundup as experienced on BPO that should be represented within PEP 595 if we are going to have a summary of "improving roundup for BPO" captured in a PEP (presumably already rejected given 581? But good to have documented regardless so _thank you_ for doing this writeup even though I realize our plan of record may be demoralizing for you).
**Flexible UI.** While Roundup UI might look dated, it is convenient and flexible.
I wholly disagree with this statement.
The BPO roundup UI drives me nuts. every. single. time. I have to use it.
It is not optimized for common workflows users actually need to accomplish
when using a bug tracker. Two example usability issues (of many): Users
can't read the latest update to a bug of length because it is hidden within
the *middle* of the scrolling region, they must hunt for it. After
reading, the text box to add to the discussion is oddly located near the
*top* of the scrolling region so that a user cannot see context of a bug
discussion they are responding to as they type. I file things like this
under "User experience design is needed for the common workflows of all
classes of users".
Roundup needs a modern responsive web interface, not GET/POST request based
interface seen on BPO. As a result of that, roundup *feels* like is
belongs in the Pre-2004 era interface wise by being web form and full page
reload server for everything. A responsive modern "async javascript
requests happen in the background of the UI" system that we all expect of
any web UI is needed. Not just tweaking the existing thing to have a mobile
friendly version of the web form. This includes persistent connections so
that updates to an issue show up live as they happen instead of getting an
error message "someone/something else has updated this issue since you
started typing, the action you wanted to take such as submitting that
comment or editing that field is now invalid and cannot be completed
without a lot of manual work figuring out what happened, cut and pasting,
and fixing things up on the you the users part".
I'm not going to try proposing a PR to this PEP encapsulating that, I'll
leave that up to anyone willing to wrangle such a PEP. The list archive
has it regardless now. :)
-Greg
On Thu, May 23, 2019 at 1:17 PM Ezio Melotti
Hello, Berker and I have been working on a PEP that suggests we keep using and improving bugs.python.org and Roundup instead of switching to GitHub Issues as proposed by PEP 581.
The PEP covers: * What are the advantages of Roundup over GitHub issues; * What features are missing in Roundup and how can we add them; * Issues with PEP 581; * Issues with the migration plan proposed by PEP 588;
The rendered version of PEP 595 is available at https://www.python.org/dev/peps/pep-0595/
For reference, you can consult PEP 581 and 588 at https://www.python.org/dev/peps/pep-0581/ and https://www.python.org/dev/peps/pep-0588/
The full text of the PEP is include below. We are planning to update the PEP to include the feedback we receive and to update the status of features as we implement them (we also have a Google Summer of Code students working on it).
Best Regards, Ezio Melotti
================ 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.
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.
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
.. [#] 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.20rati...
.. [#] 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: _______________________________________________ python-committers mailing list python-committers@python.org https://mail.python.org/mailman/listinfo/python-committers Code of Conduct: https://www.python.org/psf/codeofconduct/
On Fri, May 24, 2019, 20:23 Gregory P. Smith
-cc: committers to avoid crossposting.
+1 (I wanted to include committers, since the announcement about PEP 581 was posted there too, but it's better to keep the discussion here)
I have feedback for roundup as experienced on BPO that should be represented within PEP 595 if we are going to have a summary of "improving roundup for BPO" captured in a PEP (presumably already rejected given 581? But good to have documented regardless so _thank you_ for doing this writeup even though I realize our plan of record may be demoralizing for you).
We would like people to re-evaluate the decision, but if that doesn't happen I think the PEP is still useful, since it provides a fair view of Roundup capabilities and discusses things that we will have to take into account if we proceed with the migration -- that's why we decided to go ahead and write the PEP.
**Flexible UI.** While Roundup UI might look dated, it is convenient and flexible.
I wholly disagree with this statement.
The BPO roundup UI drives me nuts. every. single. time. I have to use it. It is not optimized for common workflows users actually need to accomplish when using a bug tracker. Two example usability issues (of many): Users can't read the latest update to a bug of length because it is hidden within the *middle* of the scrolling region, they must hunt for it.
This came up in the past, and two solutions have been proposed already: 1) keyboard shortcuts have been added in the issue page to quickly jump to the first/previous/next/last message and to the response box [0]. They support both mnemonic (f/p/n/l/r) and vim-style (h/k/j/l/i) combinations. You can find a summary table in the left sidebar of the issue page, under help -> keyboard shortcuts. 2) a patch to collapse the history by default (so that the last message was at the end of the page) was proposed and merged [1], but it was reverted after a few days because some devs wanted direct access to the history without having to do an extra click every time to expand it. After reading, the text box to add to the discussion is oddly located near
the *top* of the scrolling region so that a user cannot see context of a bug discussion they are responding to as they type.
This has also been discussed and different people had different opinion. Some suggested to reverse the order of the messages so that the last message is at the top near the reply box (like Twitter does), but other said it's unnatural to read. Some suggested to put the reply box at the bottom; however if the other fields are left at the top you would have to go back up to set them, and if they are moved down you won't easily see them at the top when you open an existing issue. Another solution is duplicating the fields and response box at the top and bottom. What I mean with *flexible* when I wrote the PEP, is that, unlike GitHub (where they decide), we can customize bpo however we want (as long as we agree on what we want -- we could even have per-user settings if we really want to :) I think I last heard discussion on the position of the response box in 2011 (when shortcuts and history collapsing were discussed). Maybe people didn't care enough about it so they didn't bother bringing it up or they didn't know it could be changed. If people do speak up, we can change bpo/Roundup. I file things like this under "User experience design is needed for the
common workflows of all classes of users".
Roundup needs a modern responsive web interface, not GET/POST request based interface seen on BPO. As a result of that, roundup *feels* like is belongs in the Pre-2004 era interface wise by being web form and full page reload server for everything. A responsive modern "async javascript requests happen in the background of the UI" system that we all expect of any web UI is needed. Not just tweaking the existing thing to have a mobile friendly version of the web form. This includes persistent connections so that updates to an issue show up live as they happen instead of getting an error message "someone/something else has updated this issue since you started typing, the action you wanted to take such as submitting that comment or editing that field is now invalid and cannot be completed without a lot of manual work figuring out what happened, cut and pasting, and fixing things up on the you the users part".
This is a good point and I think it can be done now that Roundup has a REST API.
I'm not going to try proposing a PR to this PEP encapsulating that, I'll leave that up to anyone willing to wrangle such a PEP. The list archive has it regardless now. :)
Thanks a lot for the feedback, I'll update the PEP once I get back to a PC (using mobile now). Best Regards, Ezio Melotti [0]: https://bitbucket.org/python/tracker-cpython/commits/dbe3912f93895cd1c44fd35... [1]: https://bitbucket.org/python/tracker-cpython/commits/525d3e387a65c4ada41eaa1...
-Greg
On Fri, May 24, 2019 at 1:48 PM Ezio Melotti
On Fri, May 24, 2019, 20:23 Gregory P. Smith
wrote: -cc: committers to avoid crossposting.
+1 (I wanted to include committers, since the announcement about PEP 581 was posted there too, but it's better to keep the discussion here)
I have feedback for roundup as experienced on BPO that should be represented within PEP 595 if we are going to have a summary of "improving roundup for BPO" captured in a PEP (presumably already rejected given 581? But good to have documented regardless so _thank you_ for doing this writeup even though I realize our plan of record may be demoralizing for you).
We would like people to re-evaluate the decision, but if that doesn't happen I think the PEP is still useful, since it provides a fair view of Roundup capabilities and discusses things that we will have to take into account if we proceed with the migration -- that's why we decided to go ahead and write the PEP.
**Flexible UI.** While Roundup UI might look dated, it is convenient and flexible.
I wholly disagree with this statement.
The BPO roundup UI drives me nuts. every. single. time. I have to use it. It is not optimized for common workflows users actually need to accomplish when using a bug tracker. Two example usability issues (of many): Users can't read the latest update to a bug of length because it is hidden within the *middle* of the scrolling region, they must hunt for it.
This came up in the past, and two solutions have been proposed already: 1) keyboard shortcuts have been added in the issue page to quickly jump to the first/previous/next/last message and to the response box [0]. They support both mnemonic (f/p/n/l/r) and vim-style (h/k/j/l/i) combinations. You can find a summary table in the left sidebar of the issue page, under help -> keyboard shortcuts. 2) a patch to collapse the history by default (so that the last message was at the end of the page) was proposed and merged [1], but it was reverted after a few days because some devs wanted direct access to the history without having to do an extra click every time to expand it.
After reading, the text box to add to the discussion is oddly located near
the *top* of the scrolling region so that a user cannot see context of a bug discussion they are responding to as they type.
This has also been discussed and different people had different opinion. Some suggested to reverse the order of the messages so that the last message is at the top near the reply box (like Twitter does), but other said it's unnatural to read. Some suggested to put the reply box at the bottom; however if the other fields are left at the top you would have to go back up to set them, and if they are moved down you won't easily see them at the top when you open an existing issue. Another solution is duplicating the fields and response box at the top and bottom.
The two other modern bugtracker UIs I use on a regular basis do this by having all such non-conversation metainfo in a persistent top and side bar boxes such that it is always present. Keeping the conversation and metainfo changes listed in order (latest message at the bottom, metainfo deltas interspersed in between messages all ordered/grouped by timestamp, and reply text entry box below that. These two are typically big-screen engineering UIs (github being one of them), if mobile is desired i expect these would effectively wind up as a multi-pane UI. There's a third ticket that I use for non-engineering stuff which does things in reverse order with the text entry up top and messages in reverse chronological order below that. This reversal always annoys me; probably because I spend most of my time in the others so it forces me to do headstands. I don't know if there is a *right* answer between the two approaches, I just know what I prefer. But the common theme is keeping new the update UI elements right next to the most recent entries which is what BPO lacks today. What I mean with *flexible* when I wrote the PEP, is that, unlike GitHub
(where they decide), we can customize bpo however we want (as long as we agree on what we want -- we could even have per-user settings if we really want to :)
Definitely true in that sense. Custom things, no matter where, are custom code. diverge from an upstream project in our own fork and maintenance and updates become harder. Author a pile of bots to automate tasks within a standard API or UI (as is working great for our Github PR workflow) and the equivalent maintenance burden falls on keeping the bots working. I think I last heard discussion on the position of the response box in 2011
(when shortcuts and history collapsing were discussed). Maybe people didn't care enough about it so they didn't bother bringing it up or they didn't know it could be changed. If people do speak up, we can change bpo/Roundup.
I file things like this under "User experience design is needed for the
common workflows of all classes of users".
Roundup needs a modern responsive web interface, not GET/POST request based interface seen on BPO. As a result of that, roundup *feels* like is belongs in the Pre-2004 era interface wise by being web form and full page reload server for everything. A responsive modern "async javascript requests happen in the background of the UI" system that we all expect of any web UI is needed. Not just tweaking the existing thing to have a mobile friendly version of the web form. This includes persistent connections so that updates to an issue show up live as they happen instead of getting an error message "someone/something else has updated this issue since you started typing, the action you wanted to take such as submitting that comment or editing that field is now invalid and cannot be completed without a lot of manual work figuring out what happened, cut and pasting, and fixing things up on the you the users part".
This is a good point and I think it can be done now that Roundup has a REST API.
Agreed, that seemed likely to be a pre-requisite. I don't know how many other non-bpo roundup users are out there, but even as CPython moves away from roundup, the other users would presumably appreciate such a UI. It'd also be a good educational project for anyone wanting to learn how to construct such things on top of an existing system. -gps
On Fri, May 24, 2019, 23:14 Gregory P. Smith
On Fri, May 24, 2019 at 1:48 PM Ezio Melotti
wrote: On Fri, May 24, 2019, 20:23 Gregory P. Smith
wrote: -cc: committers to avoid crossposting.
+1 (I wanted to include committers, since the announcement about PEP 581 was posted there too, but it's better to keep the discussion here)
I have feedback for roundup as experienced on BPO that should be represented within PEP 595 if we are going to have a summary of "improving roundup for BPO" captured in a PEP (presumably already rejected given 581? But good to have documented regardless so _thank you_ for doing this writeup even though I realize our plan of record may be demoralizing for you).
We would like people to re-evaluate the decision, but if that doesn't happen I think the PEP is still useful, since it provides a fair view of Roundup capabilities and discusses things that we will have to take into account if we proceed with the migration -- that's why we decided to go ahead and write the PEP.
**Flexible UI.** While Roundup UI might look dated, it is convenient and flexible.
I wholly disagree with this statement.
The BPO roundup UI drives me nuts. every. single. time. I have to use it. It is not optimized for common workflows users actually need to accomplish when using a bug tracker. Two example usability issues (of many): Users can't read the latest update to a bug of length because it is hidden within the *middle* of the scrolling region, they must hunt for it.
This came up in the past, and two solutions have been proposed already: 1) keyboard shortcuts have been added in the issue page to quickly jump to the first/previous/next/last message and to the response box [0]. They support both mnemonic (f/p/n/l/r) and vim-style (h/k/j/l/i) combinations. You can find a summary table in the left sidebar of the issue page, under help -> keyboard shortcuts. 2) a patch to collapse the history by default (so that the last message was at the end of the page) was proposed and merged [1], but it was reverted after a few days because some devs wanted direct access to the history without having to do an extra click every time to expand it.
After reading, the text box to add to the discussion is oddly located
near the *top* of the scrolling region so that a user cannot see context of a bug discussion they are responding to as they type.
This has also been discussed and different people had different opinion. Some suggested to reverse the order of the messages so that the last message is at the top near the reply box (like Twitter does), but other said it's unnatural to read. Some suggested to put the reply box at the bottom; however if the other fields are left at the top you would have to go back up to set them, and if they are moved down you won't easily see them at the top when you open an existing issue. Another solution is duplicating the fields and response box at the top and bottom.
The two other modern bugtracker UIs I use on a regular basis do this by having all such non-conversation metainfo in a persistent top and side bar boxes such that it is always present. Keeping the conversation and metainfo changes listed in order (latest message at the bottom, metainfo deltas interspersed in between messages all ordered/grouped by timestamp, and reply text entry box below that. These two are typically big-screen engineering UIs (github being one of them), if mobile is desired i expect these would effectively wind up as a multi-pane UI. There's a third ticket that I use for non-engineering stuff which does things in reverse order with the text entry up top and messages in reverse chronological order below that. This reversal always annoys me; probably because I spend most of my time in the others so it forces me to do headstands. I don't know if there is a *right* answer between the two approaches, I just know what I prefer. But the common theme is keeping new the update UI elements right next to the most recent entries which is what BPO lacks today.
What I mean with *flexible* when I wrote the PEP, is that, unlike GitHub
(where they decide), we can customize bpo however we want (as long as we agree on what we want -- we could even have per-user settings if we really want to :)
Definitely true in that sense. Custom things, no matter where, are custom code. diverge from an upstream project in our own fork and maintenance and updates become harder. Author a pile of bots to automate tasks within a standard API or UI (as is working great for our Github PR workflow) and the equivalent maintenance burden falls on keeping the bots working.
To clarify, Roundup allows you by design to define instances where you can customize the schema (i.e. classes, fields, permissions), templates, and extensions. They provide a default instance that you can start with, but it is expected that you customize it. In every new release they tell you if anything changed and how to update your instances (so far upgrading it's always been quite straightforward). We have a fork of the Roundup core only because it's faster to implement new features, test them, and then contribute them upstream, but otherwise is not required to run customized instances. That said, your point that custom things, no matter where, need to be maintained still stands.
I think I last heard discussion on the position of the response box in
2011 (when shortcuts and history collapsing were discussed). Maybe people didn't care enough about it so they didn't bother bringing it up or they didn't know it could be changed. If people do speak up, we can change bpo/Roundup.
I file things like this under "User experience design is needed for the
common workflows of all classes of users".
Roundup needs a modern responsive web interface, not GET/POST request based interface seen on BPO. As a result of that, roundup *feels* like is belongs in the Pre-2004 era interface wise by being web form and full page reload server for everything. A responsive modern "async javascript requests happen in the background of the UI" system that we all expect of any web UI is needed. Not just tweaking the existing thing to have a mobile friendly version of the web form. This includes persistent connections so that updates to an issue show up live as they happen instead of getting an error message "someone/something else has updated this issue since you started typing, the action you wanted to take such as submitting that comment or editing that field is now invalid and cannot be completed without a lot of manual work figuring out what happened, cut and pasting, and fixing things up on the you the users part".
This is a good point and I think it can be done now that Roundup has a REST API.
Agreed, that seemed likely to be a pre-requisite. I don't know how many other non-bpo roundup users are out there, but even as CPython moves away from roundup, the other users would presumably appreciate such a UI. It'd also be a good educational project for anyone wanting to learn how to construct such things on top of an existing system.
We have a Google Summer of Code student working on it over the summer. If we switch to GitHub issues, upstream Roundup and all other projects using it will still benefit from his work.
-gps
On Thu, May 23, 2019 at 10:17 PM Ezio Melotti
Hello, Berker and I have been working on a PEP that suggests we keep using and improving bugs.python.org and Roundup instead of switching to GitHub Issues as proposed by PEP 581.
The PEP covers: * What are the advantages of Roundup over GitHub issues; * What features are missing in Roundup and how can we add them; * Issues with PEP 581; * Issues with the migration plan proposed by PEP 588;
The rendered version of PEP 595 is available at https://www.python.org/dev/peps/pep-0595/
For reference, you can consult PEP 581 and 588 at https://www.python.org/dev/peps/pep-0581/ and https://www.python.org/dev/peps/pep-0588/
The full text of the PEP is include below. We are planning to update the PEP to include the feedback we receive and to update the status of features as we implement them (we also have a Google Summer of Code students working on it).
Best Regards, Ezio Melotti
Hello,
earlier today I expanded and reworded the "Migration considerations"
section and added the feedback I got from the replies.
You can find the rendered version of that section (and the rest of the
PEP) at https://www.python.org/dev/peps/pep-0595/#migration-considerations
The changeset can be found at
https://github.com/python/peps/commit/b3f4c8eb09d1987d00785cad385adf7e039477...
The full text of the latest version of the PEP is included below.
Best Regards,
Ezio Melotti
================
PEP: 595
Title: Improving bugs.python.org
Author: Ezio Melotti
I second this.
There are currently ~7000 bugs open on bugs.python.org. The Web UI
makes a good job of actually being able to navigate through these bugs,
search through them, etc.
Did the Steering Council conduct a usability study of Github Issues
with those ~7000 bugs open? If not, then I think the acceptance of
migrating to Github is a rushed job. Please reconsider.
Regards
Antoine.
On Thu, 23 May 2019 22:17:24 +0200
Ezio Melotti
Hello, Berker and I have been working on a PEP that suggests we keep using and improving bugs.python.org and Roundup instead of switching to GitHub Issues as proposed by PEP 581.
The PEP covers: * What are the advantages of Roundup over GitHub issues; * What features are missing in Roundup and how can we add them; * Issues with PEP 581; * Issues with the migration plan proposed by PEP 588;
The rendered version of PEP 595 is available at https://www.python.org/dev/peps/pep-0595/
For reference, you can consult PEP 581 and 588 at https://www.python.org/dev/peps/pep-0581/ and https://www.python.org/dev/peps/pep-0588/
The full text of the PEP is include below. We are planning to update the PEP to include the feedback we receive and to update the status of features as we implement them (we also have a Google Summer of Code students working on it).
Best Regards, Ezio Melotti
================ 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.
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.
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
.. [#] 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.20rati...
.. [#] 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:
On Fri, May 31, 2019 at 1:23 AM Antoine Pitrou
I second this.
There are currently ~7000 bugs open on bugs.python.org. The Web UI makes a good job of actually being able to navigate through these bugs, search through them, etc.
Did the Steering Council conduct a usability study of Github Issues with those ~7000 bugs open?
What I can personally speak to is I work on https://github.com/microsoft/vscode-python for a living and we're at 928 issues. I also interact with and know the team behind https://github.com/microsoft/vscode at 5,439 issues. https://github.com/rust-lang/rust/ is as 4,806. https://github.com/golang/go is at 4,467. Whether it's 928 or 5,439, to me both numbers are well beyond being small enough to remember everything in the repo and having to rely on search, labels, etc. to find anything and it's worked out for me and my team at work. The VS Code team has also never told me that they were unhappy with GitHub for their issue tracker at their scale either (I've chatted to them about their automatic classification bot and they just gave an internal talk on how they manage the project). -Brett
If not, then I think the acceptance of migrating to Github is a rushed job. Please reconsider.
Regards
Antoine.
Hello, Berker and I have been working on a PEP that suggests we keep using and improving bugs.python.org and Roundup instead of switching to GitHub Issues as proposed by PEP 581.
The PEP covers: * What are the advantages of Roundup over GitHub issues; * What features are missing in Roundup and how can we add them; * Issues with PEP 581; * Issues with the migration plan proposed by PEP 588;
The rendered version of PEP 595 is available at https://www.python.org/dev/peps/pep-0595/
For reference, you can consult PEP 581 and 588 at https://www.python.org/dev/peps/pep-0581/ and https://www.python.org/dev/peps/pep-0588/
The full text of the PEP is include below. We are planning to update the PEP to include the feedback we receive and to update the status of features as we implement them (we also have a Google Summer of Code students working on it).
Best Regards, Ezio Melotti
================ 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.
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
On Thu, 23 May 2019 22:17:24 +0200 Ezio Melotti
wrote: 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.
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
.. [#] 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.20rati...
.. [#] 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:
_______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/brett%40python.org
On May 31, 2019, at 01:22, Antoine Pitrou
I second this.
There are currently ~7000 bugs open on bugs.python.org. The Web UI makes a good job of actually being able to navigate through these bugs, search through them, etc.
Did the Steering Council conduct a usability study of Github Issues with those ~7000 bugs open? If not, then I think the acceptance of migrating to Github is a rushed job. Please reconsider.
Thanks for your feedback Antoine. This is a tricky issue, with many factors and tradeoffs to consider. I really appreciate Ezio and Berker working on PEP 595, so we can put all these issues on the table. I think one of the most important tradeoffs is balancing the needs of existing developers (those who actively triage bugs today), and future contributors. But this and other UX issues are difficult to compare on our actual data right now. I fully expect that just as with the switch to git, we’ll do lots of sample imports and prototyping to ensure that GitHub issues will actually work for us (given our unique requirements), and to help achieve the proper balance. It does us no good to switch if we just anger all the existing devs. IMHO, if the switch to GH doesn’t improve our workflow, then it definitely warrants a reevaluation. I think things will be better, but let’s prove it. -Barry
On Fri, May 31, 2019 at 11:39 AM Barry Warsaw
On May 31, 2019, at 01:22, Antoine Pitrou
wrote: I second this.
There are currently ~7000 bugs open on bugs.python.org. The Web UI makes a good job of actually being able to navigate through these bugs, search through them, etc.
Did the Steering Council conduct a usability study of Github Issues with those ~7000 bugs open? If not, then I think the acceptance of migrating to Github is a rushed job. Please reconsider.
Thanks for your feedback Antoine.
This is a tricky issue, with many factors and tradeoffs to consider. I really appreciate Ezio and Berker working on PEP 595, so we can put all these issues on the table.
I think one of the most important tradeoffs is balancing the needs of existing developers (those who actively triage bugs today), and future contributors. But this and other UX issues are difficult to compare on our actual data right now. I fully expect that just as with the switch to git, we’ll do lots of sample imports and prototyping to ensure that GitHub issues will actually work for us (given our unique requirements), and to help achieve the proper balance. It does us no good to switch if we just anger all the existing devs.
IMHO, if the switch to GH doesn’t improve our workflow, then it definitely warrants a reevaluation. I think things will be better, but let’s prove it.
Perhaps we should put an explicit step on the transition plan, after the prototyping, that's "gather feedback from prototypes, re-evaluate, make final go/no-go decision"? I assume we'll want to do that anyway, and having it formally written down might reassure people. It might also encourage more people to actually try out the prototypes if we make it very clear that they're going to be asked for feedback. -n -- Nathaniel J. Smith -- https://vorpus.org
Nathaniel Smith wrote:
On Fri, May 31, 2019 at 11:39 AM Barry Warsaw
wrote: On May 31, 2019, at 01:22, Antoine Pitrou
wrote: I second this.
There are currently ~7000 bugs open on bugs.python.org. The Web UI makes a good job of actually being able to navigate through these bugs, search through them, etc.
Did the Steering Council conduct a usability study of Github Issues with those ~7000 bugs open? If not, then I think the acceptance of migrating to Github is a rushed job. Please reconsider.
Thanks for your feedback Antoine.
This is a tricky issue, with many factors and tradeoffs to consider. I really appreciate Ezio and Berker working on PEP 595, so we can put all these issues on the table.
I think one of the most important tradeoffs is balancing the needs of existing developers (those who actively triage bugs today), and future contributors. But this and other UX issues are difficult to compare on our actual data right now. I fully expect that just as with the switch to git, we’ll do lots of sample imports and prototyping to ensure that GitHub issues will actually work for us (given our unique requirements), and to help achieve the proper balance. It does us no good to switch if we just anger all the existing devs.
IMHO, if the switch to GH doesn’t improve our workflow, then it definitely warrants a reevaluation. I think things will be better, but let’s prove it.
Perhaps we should put an explicit step on the transition plan, after the prototyping, that's "gather feedback from prototypes, re-evaluate, make final go/no-go decision"? I assume we'll want to do that anyway, and having it formally written down might reassure people. It might also encourage more people to actually try out the prototypes if we make it very clear that they're going to be asked for feedback.
-n
As Barry mentioned, there are many considerations. - Will GitHub provide a similar experience as bpo? Can the features valued by existing developers be served in a suitable way by GitHub issues? - What opportunity costs exist for remaining on bpo? Planning, reporting, integration with services, and accessibility are some. - Chicken and egg question: Are there 7000 open issues because the existing workflow with bpo inhibits acting on open issues with patches? Antoine, as for large projects on GitHub with many issues, TypeScript is a reasonable proxy with close to 4000 open issues yet only 126 open PRs. There are some nice planning things that have been done in the repo https://github.com/microsoft/TypeScript/issues as well as good documentation around their process and workflow. Thanks to Ezio and Berker for raising points in PEP 595. - Carol
On Fri, 31 May 2019 11:58:22 -0700
Nathaniel Smith
On Fri, May 31, 2019 at 11:39 AM Barry Warsaw
wrote: On May 31, 2019, at 01:22, Antoine Pitrou
wrote: I second this.
There are currently ~7000 bugs open on bugs.python.org. The Web UI makes a good job of actually being able to navigate through these bugs, search through them, etc.
Did the Steering Council conduct a usability study of Github Issues with those ~7000 bugs open? If not, then I think the acceptance of migrating to Github is a rushed job. Please reconsider.
Thanks for your feedback Antoine.
This is a tricky issue, with many factors and tradeoffs to consider. I really appreciate Ezio and Berker working on PEP 595, so we can put all these issues on the table.
I think one of the most important tradeoffs is balancing the needs of existing developers (those who actively triage bugs today), and future contributors. But this and other UX issues are difficult to compare on our actual data right now. I fully expect that just as with the switch to git, we’ll do lots of sample imports and prototyping to ensure that GitHub issues will actually work for us (given our unique requirements), and to help achieve the proper balance. It does us no good to switch if we just anger all the existing devs.
IMHO, if the switch to GH doesn’t improve our workflow, then it definitely warrants a reevaluation. I think things will be better, but let’s prove it.
Perhaps we should put an explicit step on the transition plan, after the prototyping, that's "gather feedback from prototypes, re-evaluate, make final go/no-go decision"? I assume we'll want to do that anyway, and having it formally written down might reassure people. It might also encourage more people to actually try out the prototypes if we make it very clear that they're going to be asked for feedback.
Indeed, regardless of the exact implementation details, I think "try first, decide after" is the right procedure here. Regards Antoine.
On Sat, Jun 1, 2019 at 11:50 AM Antoine Pitrou
On Fri, 31 May 2019 11:58:22 -0700 Nathaniel Smith
wrote: On Fri, May 31, 2019 at 11:39 AM Barry Warsaw
wrote: On May 31, 2019, at 01:22, Antoine Pitrou
wrote: I second this.
There are currently ~7000 bugs open on bugs.python.org. The Web UI makes a good job of actually being able to navigate through these bugs, search through them, etc.
Did the Steering Council conduct a usability study of Github Issues with those ~7000 bugs open? If not, then I think the acceptance of migrating to Github is a rushed job. Please reconsider.
Thanks for your feedback Antoine.
This is a tricky issue, with many factors and tradeoffs to consider. I really appreciate Ezio and Berker working on PEP 595, so we can put all these issues on the table.
I think one of the most important tradeoffs is balancing the needs of existing developers (those who actively triage bugs today), and future contributors.
These can be further divided in several groups: from core devs and release managers, to triagers, to regular and occasional contributors, to people that just want to report an issue and be done with it, to people that think the error they just got is a Python bug, each of them with different goals and needs. I think that rather than discussing whether GitHub Issues is better or worse than Roundup, we should first try to understand who is facing what issues now, and who will face what issues after the switch. This can be done both by gathering feedback from different types of people and by testing and comparing the solutions (see below). Once we know what the issues are, we should evaluate if and how we can address them, and also -- if we can't make everyone happy -- what groups of people we want to prioritize (e.g. do we want core devs to be more effective at dealing with the thousands of already existing issues, or we want to make it easier for users to report new bugs?).
But this and other UX issues are difficult to compare on our actual data right now. I fully expect that just as with the switch to git, we’ll do lots of sample imports and prototyping to ensure that GitHub issues will actually work for us (given our unique requirements), and to help achieve the proper balance. It does us no good to switch if we just anger all the existing devs.
IMHO, if the switch to GH doesn’t improve our workflow, then it definitely warrants a reevaluation. I think things will be better, but let’s prove it.
Perhaps we should put an explicit step on the transition plan, after the prototyping, that's "gather feedback from prototypes, re-evaluate, make final go/no-go decision"? I assume we'll want to do that anyway, and having it formally written down might reassure people. It might also encourage more people to actually try out the prototypes if we make it very clear that they're going to be asked for feedback.
Indeed, regardless of the exact implementation details, I think "try first, decide after" is the right procedure here.
Testing a change of this magnitude is not trivial. I can see several possible options: * using the on-demand approach proposed by PEP 588, a full migration, or some other solution (e.g. parallel, synced trackers); * doing a throwaway test migration (import zero/some/all existing issues, then discard any new message/issue at the end of the test) or using real issues directly (import zero/some/all issues and keep adding real messages/issues); * if we do a test migration and it works, we might need to do a second, real migration, possibly involving the GH staff twice; if it doesn't work, we discard everything and that's it; * if we use real issues, we might need to migrate things back to Roundup if GH doesn't fit our needs and it might be confusing for users; * starting from scratch on GH with new issues (at least initially, for testing purposes) or porting some/all issues from bpo; * if we start from scratch we don't need to write the tools to migrate, but we won't have feedback about searching/navigating through lot of issues; * if we port some/all the issues, we need to write the tools to do it, even if it's just for testing purposes and we end going back to Roundup; * limiting the test to triagers/core-devs, or involve regular users; * if we involve regular users we might get better feedback, but there's risk of confusion (afaik the only way to inform users on GitHub Issues is writing another bot that adds messages) and backlash; * doing separate specific tests (e.g. having a read-only repo with all the issues to test search/navigation, and a separate read-write repo to test issue creation) or a "real-world" test; * some specific tests might be easier to setup (e.g. issue creation test using templates), but for others we still need to import some/all the issues; If we agree on testing, I think we need to discuss the options, define and document a list of steps, and start working on it. Best Regards, Ezio Melotti
Regards
Antoine.
participants (7)
-
Antoine Pitrou
-
Barry Warsaw
-
Brett Cannon
-
Carol Willing
-
Ezio Melotti
-
Gregory P. Smith
-
Nathaniel Smith