PEP 595: replace mismatched references with inline links (#2534)
* PEP 595: replace mismatched references with inline links * PEP 595: use plaintext instead of Python formatting * PEP 595: remove redundant Emacs stanza
This commit is contained in:
Hugo van Kemenade
GitHub
parent
adf9512d96
commit
42e241fac4
200
pep-0595.rst
200
pep-0595.rst
|
|
@ -28,9 +28,11 @@ informational PEP.
|
|||
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
|
||||
On May 14th, 2019 :pep:`581` has been `accepted
|
||||
<https://mail.python.org/pipermail/python-dev/2019-May/157399.html>`_
|
||||
without much public discussion and `without a clear consensus
|
||||
<https://mail.python.org/pipermail/python-committers/2019-May/006755.html>`_.
|
||||
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,
|
||||
|
|
@ -98,13 +100,16 @@ on GitHub Issues.
|
|||
|
||||
* **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.
|
||||
are automatically updated when the `experts index
|
||||
<https://devguide.python.org/experts/>`_ 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 [#]_.
|
||||
(for example, `bpo-12078 <https://bugs.python.org/issue12078>`_).
|
||||
The list of dependencies can also be used to create
|
||||
meta-issues that references several other sub-issues
|
||||
(for example, `bpo-26865 <https://bugs.python.org/issue26865>`_).
|
||||
|
||||
|
||||
Improving Roundup
|
||||
|
|
@ -115,7 +120,7 @@ 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.
|
||||
services and the development of new tools and applications easier.
|
||||
|
||||
Upstream Roundup now supports a REST API. Updating the tracker will
|
||||
make the REST API available.
|
||||
|
|
@ -125,15 +130,17 @@ by improving Roundup and/or our instance.
|
|||
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 [#]_.
|
||||
A patch to add this functionality is `already available
|
||||
<https://github.com/python/bugs.python.org/issues/7>`_
|
||||
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 [#]_.
|
||||
have been proposed on the `roundup-devel mailing list
|
||||
<https://sourceforge.net/p/roundup/mailman/message/36667828/>`_.
|
||||
|
||||
* **"Remove me from nosy list" button.** Add a button on issue pages
|
||||
to remove self from the nosy list.
|
||||
|
|
@ -160,14 +167,18 @@ by improving Roundup and/or our instance.
|
|||
* **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::
|
||||
A `patch <https://mail.python.org/pipermail/tracker-discuss/2018-June/004547.html>`_
|
||||
is available to change the content of the bpo emails from:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
components: +Tkinter
|
||||
versions: +Python 3.4
|
||||
pull_requests: +42
|
||||
|
||||
to::
|
||||
to:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
components: +Tkinter
|
||||
versions: +Python 3.4
|
||||
|
|
@ -222,7 +233,8 @@ are currently supported:
|
|||
* 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.
|
||||
See `this message <https://bugs.python.org/issue36951#msg342882>`_
|
||||
for a recent example of this feature.
|
||||
|
||||
* "Support for permalinks, allowing easy quoting and copying &
|
||||
pasting of source code."
|
||||
|
|
@ -239,15 +251,19 @@ are currently supported:
|
|||
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.
|
||||
features rather than expanding. `This webhook
|
||||
<https://github.com/berkerpeksag/cpython-emailer-webhook>`_
|
||||
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.
|
||||
has also maintenance cost. `This recent incident caused by GitHub
|
||||
<https://github.com/python/bedevere/pull/163>`_
|
||||
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 [#]_).
|
||||
we currently host/maintain (`Jython <https://bugs.jython.org/>`_
|
||||
and `Roundup <https://issues.roundup-tracker.org/>`_).
|
||||
|
||||
The "Issues with Roundup / bpo" section of :pep:`581` lists some issues
|
||||
that have already been fixed:
|
||||
|
|
@ -256,8 +272,11 @@ that have already been fixed:
|
|||
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 [#]_ [#]_.
|
||||
* While Roundup uses Mercurial by default, there is a `git clone
|
||||
available on GitHub <https://github.com/roundup-tracker/roundup>`_.
|
||||
Roundup also has CI available on `Travis CI
|
||||
<https://github.com/roundup-tracker/roundup>`_ and `Codecov
|
||||
<https://codecov.io/gh/roundup-tracker/roundup/commits>`_.
|
||||
|
||||
* "There is no REST API available. There is an open issue in Roundup for
|
||||
adding REST API. Last activity was in 2016."
|
||||
|
|
@ -271,7 +290,8 @@ that have already been fixed:
|
|||
|
||||
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
|
||||
The "Email address" column from the `user listing page
|
||||
<https://bugs.python.org/user?@sort=username>`_ has been
|
||||
removed too.
|
||||
|
||||
* "It sends a number of unnecessary emails and notifications, and it is
|
||||
|
|
@ -362,11 +382,12 @@ need to be addressed regardless of the approach used:
|
|||
redirects and preserve external links to GitHub issues.
|
||||
|
||||
* **References preservation and updating.** In addition to issue
|
||||
references, bpo converts a number of other references into links,
|
||||
references, bpo `converts a number of other references into links
|
||||
<https://devguide.python.org/triaging/#generating-special-links-in-a-comment>`_,
|
||||
including message and PR IDs, changeset numbers, legacy SVN
|
||||
revision numbers, paths to files in the repo, files in tracebacks
|
||||
(detecting the correct branch), and links to devguide pages and
|
||||
sections [#]_.
|
||||
sections.
|
||||
|
||||
Since Roundup converts references to links when messages are
|
||||
requested, it is possible to update the target and generate the
|
||||
|
|
@ -403,145 +424,38 @@ need to be addressed regardless of the approach used:
|
|||
* **Signal to noise ratio.** 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 [#]_.
|
||||
in a `Zulip topic
|
||||
<https://python.zulipchat.com/#narrow/stream/130206-pep581/topic/s.2Fn.20ratio>`_.
|
||||
|
||||
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 [#]_.
|
||||
conversation (for example, `this PR
|
||||
<https://github.com/python/cpython/pull/9099>`_.
|
||||
|
||||
* **Weekly tracker reports and stats.** 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
|
||||
issue counts (for example, see `this summary
|
||||
<https://mail.python.org/pipermail/python-dev/2019-May/157483.html>`_).
|
||||
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 [#]_.
|
||||
The data collect by the weekly report is also used to generate
|
||||
`statistics and graphs <https://bugs.python.org/issue?@template=stats>`_
|
||||
that can be used to gain new insights.
|
||||
|
||||
* **bpo-related MLs.** There are currently two mailing lists where
|
||||
bpo 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
|
||||
`new-bugs-announce <https://mail.python.org/mailman/listinfo/new-bugs-announce>`_
|
||||
and `python-bugs-list <https://mail.python.org/mailman/listinfo/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:
|
||||
|
|
|
|||
Loading…
Reference in New Issue