Overhaul the labels page to reflect current GH labeling practice (#930)

* Update the triage/labels.rst page. * Remove duplicate label. * Use the `:gh-label:` role. * Use the `:cpy-file:` role. * (Re)move (mostly) BPO-related info. * Apply suggestions from code review Co-authored-by: C.A.M. Gerlach <[email protected]> * Apply suggestions from code review Co-authored-by: C.A.M. Gerlach <[email protected]> Co-authored-by: Hugo van Kemenade <[email protected]> * Fix miss-islington link markup. * Add more ref targets to prevent link rotting. Co-authored-by: C.A.M. Gerlach <[email protected]> Co-authored-by: Hugo van Kemenade <[email protected]> * Add other two ref targets to the "Type labels" section. * Address remaining review comments. * Apply more suggestions from code review. Co-authored-by: C.A.M. Gerlach <[email protected]> * Rephrase sentence as suggested in a review comment. * Rewrap a few long lines. * Restore and move the `Assignees` sub-section. * Fix typo. Co-authored-by: Hugo van Kemenade <[email protected]> * Fix "triager" capitalization. Co-authored-by: Hugo van Kemenade <[email protected]> * Document the `automerge` label. * Remove obsolete note/comment. * Minor grammar/punctuation/phrasing fixes. Co-authored-by: C.A.M. Gerlach <[email protected]> * Final tweaks. Co-authored-by: C.A.M. Gerlach <[email protected]> --------- Co-authored-by: C.A.M. Gerlach <[email protected]> Co-authored-by: Hugo van Kemenade <[email protected]>
python · Mar 16, 2023 · 4e6e10f · 4e6e10f
1 parent 5803a02
commit 4e6e10f
Show file tree

Hide file tree

Showing 6 changed files with 181 additions and 399 deletions.
diff --git a/getting-started/pull-request-lifecycle.rst b/getting-started/pull-request-lifecycle.rst
@@ -402,6 +402,9 @@ on how to properly add the co-author info.
 
 See also :ref:`Applying a Patch to Git <git_from_patch>`.
 
+
+.. _reviewing-prs:
+
 Reviewing
 =========
 
@@ -427,7 +430,6 @@ thus iterate until a satisfactory solution has emerged.
 
 .. _how-to-review-a-pull-request:
 
-
 How to Review a Pull Request
 ----------------------------
 

diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst
@@ -577,6 +577,7 @@ support.
 For editors and tools which the core developers have felt some special comment
 is needed for coding *in* Python, see :ref:`resources`.
 
+.. _build-directory-structure:
 
 Directory structure
 ===================

diff --git a/triage/issue-tracker.rst b/triage/issue-tracker.rst
@@ -84,16 +84,44 @@ The submission form has only two fields that you need to fill:
   information as appropriate). In particular, *what version of Python* you
   were using.
 
-Understanding the issue's progress and status
----------------------------------------------
-
-There is a number of additional fields like **Assignees**, **Labels**,
-**Projects**, and **Milestone**. Those are filled by triagers and core
-developers, this is covered in the :ref:`triaging` page. You don't need
+You can tag someone, with :samp:`@{username}` in a comment,
+if you think the issue should be brought to their attention.
+Use the :ref:`experts` to know who wants to be
+tagged or assigned for specific areas.
+
+There are a number of additional fields like **Assignees**, **Labels**,
+and **Projects**. Those are filled by triagers and core
+developers and are covered in the :ref:`triaging` page. You don't need
 to worry about those when reporting issues as a Python user.
 
-You will automatically receive an update each time an action is taken on
-the bug, unless you changed your GitHub notification settings.
+Adding special links
+--------------------
+
+The following abbreviations can be used in a comment to generate a link:
+
+* :samp:`GH-{NNN}`: to link to another issue or PR;
+* :samp:`PEP-{NNN}`: to link to a specific PEP;
+* :samp:`BPO-{NNN}`: to link to a bugs.python.org issue;
+
+See also the `list of autolinks supported by GitHub <autolinks_>`_.
+
+Following issues
+----------------
+
+If you want to subscribe yourself to an issue, click the :guilabel:`🔔 Subscribe`
+button in the sidebar.  Similarly, if you were tagged by somebody else but
+decided this issue is not for you, click the :guilabel:`🔕 Unsubscribe`
+button in the sidebar.  Note that you are automatically subscribed to
+issues you created.
+
+Tracking dependencies and duplicates
+------------------------------------
+
+It is possible to use `checklists`_ to track dependencies or,
+in case of meta-issues, to link to the other related issues.
+
+By writing :samp:`Duplicate of #{NNN}` in a comment, you can
+`mark issues and PRs as duplicates <duplicates_>`_.
 
 
 Disagreement With a Resolution on the Issue Tracker
@@ -128,4 +156,7 @@ reason either as ``complete`` or ``not planned``.
 .. _devguide repo: https://github.com/python/devguide/issues
 .. _Roundup: https://roundup.sourceforge.io/
 .. _Python Discourse: https://discuss.python.org/
+.. _autolinks: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls
+.. _checklists: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists
+.. _duplicates: https://docs.github.com/en/issues/tracking-your-work-with-issues/marking-issues-or-pull-requests-as-a-duplicate
 .. _Core Development Discourse category: https://discuss.python.org/c/core-dev/23