Document using Github issues as the issue tracker (python#814)

Author: ambv

appendix.rst

@@ -44,6 +44,8 @@ Issue tracking and triaging
 
 * :doc:`tracker`
 * :doc:`triaging`
+* :doc:`gh-labels`
+* :doc:`gh-faq`
 
 Language development in depth
 -----------------------------

committing.rst

@@ -26,8 +26,7 @@ to enter the public source tree. Ask yourself the following questions:
 * **Are the changes acceptable?** 
    If you want to share your work-in-progress code on a feature or bugfix, 
    then you can open a ``WIP``-prefixed pull request, publish patches on 
-   the `issue tracker <https://bugs.python.org/>`_, or create a public 
-   fork of the repository.
+   the `issue tracker`_, or create a public fork of the repository.
 
 * **Do the checks on the pull request show that the test suite passes?** 
    Make sure that all of the status checks are passing.
@@ -56,7 +55,7 @@ to enter the public source tree. Ask yourself the following questions:
    core developers and members of the `Python Triage Team`_ can apply
    labels to GitHub pull requests).
 
-* **Does the pull request have a label indicating that the submitter has signed the CLA?** 
+* **Does the pull request pass a check indicating that the submitter has signed the CLA?** 
    Make sure that the contributor has signed a `Contributor
    Licensing Agreement <https://www.python.org/psf/contrib/contrib-form/>`_ 
    (CLA), unless their change has no possible intellectual property 
@@ -247,3 +246,5 @@ the commit message. Here is an example::
 
    Reverts python/cpython#111.
    Reason: This commit broke the buildbot.
+
+.. _issue tracker: https://github.com/python/cpython/issues

communication.rst

@@ -77,7 +77,7 @@ Most lists are also mirrored at `GMANE <https://gmane.io/>`_ and can be read and
 posted to in various ways, including via web browsers, NNTP newsreaders, and
 RSS feed readers.
 
-.. _issue tracker: https://bugs.python.org
+.. _issue tracker: https://github.com/python/cpython/issues
 .. _new-bugs-announce: https://mail.python.org/mailman/listinfo/new-bugs-announce
 .. _python-bugs-list: https://mail.python.org/mailman/listinfo/python-bugs-list
 .. _python-checkins: https://mail.python.org/mailman/listinfo/python-checkins

coverage.rst

@@ -262,8 +262,6 @@ Once you have increased coverage, you need to create an issue on the
 issue set the "Components" to "Test" and "Versions" to the version of Python you
 worked on (i.e., the in-development version).
 
-.. _issue tracker: https://bugs.python.org
-
 
 Measuring coverage of C code with gcov and lcov
 """""""""""""""""""""""""""""""""""""""""""""""
@@ -292,5 +290,6 @@ about 20 to 30 minutes on a modern computer.
     Multiple test jobs may not work properly. C coverage reporting has only
     been tested with a single test process.
 
+.. _issue tracker: https://github.com/python/cpython/issues
 .. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html
 .. _lcov: http://ltp.sourceforge.net/coverage/lcov.php

docquality.rst

@@ -62,8 +62,7 @@ If you see a documentation issue that you would like to tackle, you can:
 By following the steps in the :ref:`Quick Guide to Pull Requests <pullrequest-quickguide>`,
 you will learn the workflow for documentation pull requests.
 
-.. _issue tracker: https://bugs.python.org
-.. _documentation issues: https://bugs.python.org/issue?%40search_text=&ignore=file%3Acontent&title=&%40columns=title&id=&%40columns=id&stage=&creation=&creator=&activity=&%40columns=activity&%40sort=activity&actor=&nosy=&type=&components=4&versions=&dependencies=&assignee=&keywords=6&priority=&status=1&%40columns=status&resolution=&nosy_count=&message_count=&%40group=&%40pagesize=100&%40startwith=0&%40sortdir=on&%40queryname=&%40old-queryname=&%40action=search
+.. _documentation issues: https://github.com/python/cpython/issues?q=is%3Aissue+is%3Aopen+label%3Adocumentation
 .. _octocat: https://github.com/logos
 
 
@@ -136,3 +135,4 @@ without errors.
 .. _devguide repo: https://github.com/python/devguide
 .. _devguide GitHub tracker: https://github.com/python/devguide/issues
 .. _Sphinx: https://www.sphinx-doc.org/
+.. _issue tracker: https://github.com/python/cpython/issues

fixingissues.rst

@@ -20,6 +20,6 @@ discussion to help bring it to a close). Regardless of why the issue is open,
 you can also always provide useful comments if you do attempt a fix, successful
 or not.
 
-.. _"easy" issues: https://bugs.python.org/issue?status=1&@sort=-activity&@dispname=Easy%20issues&@startwith=0&@filter=&@group=priority&@columns=id,activity,title,creator,status&keywords=6&@action=search&@pagesize=50
+.. _"easy" issues: https://github.com/python/cpython/issues?q=is%3Aissue+is%3Aopen+label%3Aeasy
 
 .. TODO: add something about no active core developer for the area?

gh-faq.rst

@@ -0,0 +1,120 @@
+GitHub issues for BPO users
+===========================
+
+Here are some frequently asked quesions about how to do things in
+Github issues that you used to be able to do on `bpo`_.
+
+Before you ask your own question, make sure you read :doc:`tracker`
+and :doc:`triaging` (specifically including :doc:`gh-labels`) as those
+pages include a lot of introductory material.
+
+How to format my comments nicely?
+---------------------------------
+
+There is a wonderful `beginner guide to writing and formatting on Github
+<https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github>`_.
+Highly recommended.
+
+One pro-tip we can sell you right here is that if you want to paste
+some longer log as a comment, attach a file instead (see how below).
+If you still insist on pasting it in your comment, do it like this::
+
+    <details>
+    <summary>This is the summary text, click me to expand</summary>
+
+    Here goes the long, long text.
+    It will be collapsed by default!
+    </details>
+
+How to attach files to an issue?
+--------------------------------
+
+Drag them into the comment field, wait until the file uploads, and Github
+will automatically put a link to your file in your comment text.
+
+How to link to file paths in the repository when writing comments?
+------------------------------------------------------------------
+
+Use Markdown links. If you link to the default Github path, the file
+will link to the latest current version on the given branch.
+
+You can get a permanent link to a given revision of a given file by
+`pressing "y" <https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files>`_.
+
+How to do advanced searches?
+----------------------------
+
+Use the `Github search syntax`_ or the interactive `advanced search`_ form
+that generates search queries for you.
+
+Where is the "nosy list"?
+-------------------------
+
+Subscribe another person to the issue by tagging them in the comment with
+``@username``.
+
+If you want to subscribe yourself to an issue, click the *🔔 Subscribe*
+button in the sidebar.
+
+Similarly, if you were tagged by somebody else but
+decided this issue is not for you, you might click the *🔕 Unsubscribe*
+button in the sidebar.
+
+There is no exact equivalent of the "nosy list" feature, so to preserve
+this information during the transfer, we list the previous members of
+this list in the first message on the migrated issue.
+
+How to add issue dependencies?
+------------------------------
+
+Add a checkbox list like this in the issue description::
+
+    - [x] #739
+    - [ ] https://github.com/octo-org/octo-repo/issues/740
+    - [ ] Add delight to the experience when all tasks are complete :tada:
+
+then those will become sub-tasks on the given issue. Moreover, Github will
+automatically mark a task as complete if the other referenced issue is
+closed. More details in the `official Github documentation
+<https://docs.github.com/en/issues/tracking-your-work-with-issues/about-task-lists>`_.
+
+What on Earth is a "mannequin"?
+-------------------------------
+
+For issues migrated to Github from `bpo`_ where the authors or commenters
+are not core developers, we opted not to link to their Github accounts
+directly. Users not in the `python organization on Github
+<https://github.com/orgs/python/people>`_ might not like comments to
+appear under their name from an automated import.  Others never linked Github on
+`bpo`_ in the first place so linking their account, if any, would be impossible.
+
+In those cases a "mannequin" account is present to help follow the conversation
+that happened in the issue. In case the user did share their Github account
+name in their `bpo_` profile, we use that. Otherwise, their classic `bpo_`
+username is used instead.
+
+Where did the "Resolution" field go?
+------------------------------------
+
+Based on historical data we found it not being used very often.
+
+Where did the "Low", "High", and "Critical" priorities go?
+----------------------------------------------------------
+
+Based on historical data we found those not being used very often.
+
+How to find a random issue?
+---------------------------
+
+This is not supported by Github.
+
+Where are regression labels?
+----------------------------
+
+We rarely updated this information and it turned out not to be
+particularly useful outside of the change log.
+
+
+.. _bpo: https://bugs.python.org/
+.. _Github search syntax: https://docs.github.com/en/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax
+.. _advanced search: https://github.com/search/advanced

gh-labels.rst

@@ -0,0 +1,170 @@
+.. _github-labels:
+
+Github Labels
+=============
+
+We're using labels on Github to categorize issues and pull requests.
+Many labels are shared for both use cases, while some are dedicated
+only to one. Below is a possibly inexhaustive list, but it should get
+you going. For a full list, see `here <https://github.com/python/cpython/issues/labels>`_.
+
+General purpose labels
+----------------------
+
+type-behavior
+    Used for issues/PRs that address unintentional behavior, but do not
+    pose significant security concerns. Generally, bugfixes will be attached
+    to a specific issue where the unintended behavior was first reported.
+
+type-documentation
+    Used for issues/PRs that exclusively involve changes to
+    the documentation. Documentation includes `*.rst` files, docstrings,
+    and code comments.
+
+type-enhancement
+    Used for issues/PRs that provide additional functionality
+    or capabilities beyond the existing specifications.
+
+type-performance
+    Used for issues/PRs that provide performance optimizations.
+
+type-security
+    Used for issues/PRs that involve critical security issues. Less severe
+    security concerns can instead use the type-bugfix label.
+
+type-tests
+    Used for issues/PRs that exclusively involve changes to the tests.
+
+OS-Mac / OS-Windows
+    Used for issues/PRs involving changes which only have an effect upon
+    a specific operating system.
+
+spam
+    Used for issues/PRs that don't include enough eggs or bacon.
+
+Labels specific to issues
+-------------------------
+
+Priority
+^^^^^^^^
+
+release-blocker
+    The highest priority of an issue. If unaddressed, will cause the
+    release manager to hold releasing a new version of Python.
+
+deferred-blocker
+    A release blocker that was pushed one or more releases into the
+    future. Possibly a temporary workaround was employed, or the version
+    of Python the issue is affecting is still in alpha or beta stages
+    of development.
+
+Component
+^^^^^^^^^
+
+library
+    Used for issues involving Python modules in the ``Lib/`` dir.
+
+documentation
+    Used for issues involving documentation in the ``Doc/`` dir.
+
+interpreter-core
+    Used for issues in interpreter core (``Objects/``, ``Python/``,
+    ``Grammar/``, and ``Parser/`` dirs).
+
+extension-modules
+    Used for issues involving C modules in the ``Modules/`` dir.
+
+tests
+    Used for issues involving only Python's regression test suite, i.e.
+    files in the ``Lib/test/`` dir.
+
+Other
+^^^^^
+
+new
+    Denotes that the issue hasn't been looked at by triagers or core
+    developers yet.
+
+easy
+    Denotes that the issue is a good candidate for a newcomer to address.
+
+
+Labels specific to PRs
+----------------------
+
+DO-NOT-MERGE
+    Used on PRs to prevent miss-islington from being able
+    to automatically merge the pull request. This label is appropriate when a PR
+    has a non-trivial conflict with the branch it is being merged into.
+
+expert-asyncio
+    Used for PRs which involve changes to the asyncio module
+    or other asynchronous frameworks that utilize it.
+
+invalid
+    Used manually for PRs that do not meet basic requirements and
+    automatically added by bedevere when PR authors attempt to merge maintenace
+    branches into the main branch. During events such as the October
+    Hacktoberfest, this label will prevent the PR from counting toward the
+    author's contributions.
+
+needs backport to X.Y
+    Used for PRs which are appropriate to backport to
+    branches prior to main. Generally, backports to the maintenance branches
+    are primarily bugfixes and documentation clarifications. Backports to the
+    security branches are strictly reserved for PRs involving security fixes, such as
+    crashes, privilege escalation, and DoS. The use of this label will cause
+    miss-islington to attempt to automatically merge the PR into the branches
+    specified.
+
+skip issue
+    Used for PRs which involve trivial changes, such as typo fixes,
+    comment changes, and section rephrases. The majority of PRs require
+    an issue to be attached to, but if there are no code changes and the
+    section being modified retains the same meaning, this label might be
+    appropriate.
+
+skip news
+    Similar to the skip issue label, this label is used for PRs which
+    involve trivial changes, backports, or already have a relevant news entry
+    in another PR. Any potentially impactful changes should have a
+    corresponding news entry, but for trivial changes it's commonly at the
+    discretion of the PR author if they wish to opt-out of making one.
+
+sprint
+    Used for PRs authored during an in-person sprint, such as
+    at PyCon, EuroPython, or other official Python events. The label is
+    used to prioritize the review of those PRs during the sprint.
+
+stale
+    Used for PRs that include changes which are no longer relevant, or when the
+    author hasn't responded to feedback in a long period of time, or when the
+    reviewer is unresponsive. This label helps core developers quickly identify
+    PRs that are candidates for closure or require a ping to the author or
+    reviewer.
+
+awaiting review
+    Used for PRs that haven't been reviewed by anyone yet.
+
+awaiting core review
+    Used when the PR is authored by a core developer or when a non-core
+    developer has reviewed the PR, even if they requested changes.
+    Note that reviewers could have been added manually by a triager or core
+    developer, or included automatically through use of the `CODEOWNERS
+    <https://github.com/python/cpython/blob/main/.github/CODEOWNERS>`_
+    file.
+
+awaiting changes
+    A reviewer required changes to proceed with the PR.
+
+awaiting change review
+    The PR author made requested changes, and they are waiting for review.
+
+awaiting merge
+    The PR has been approved by a core developer and is ready to merge.
+
+test-with-buildbots
+    Used on PRs to test the latest commit with the buildbot fleet. Generally for
+    PRs with large code changes requiring more testing before merging. This
+    may take multiple hours to complete. Triagers can also stop a stuck build
+    using the web interface.

help.rst

@@ -121,4 +121,4 @@ you detail which conditions triggered it (including the OS name and version,
 and what you were trying to do), as well as the exact error message you
 encountered.
 
-.. _issue tracker: https://bugs.python.org
+.. _issue tracker: https://github.com/python/cpython/issues

index.rst

@@ -341,5 +341,5 @@ Full Table of Contents
 .. _Jython: https://www.jython.org/
 .. _IronPython: https://ironpython.net/
 .. _Stackless: https://github.com/stackless-dev/stackless/wiki/
-.. _Issue tracker: https://bugs.python.org/
+.. _Issue tracker: https://github.com/python/cpython/issues
 .. _open pull requests: https://github.com/python/cpython/pulls?utf8=%E2%9C%93&q=is%3Apr%20is%3Aopen%20label%3A%22awaiting%20review%22