From 79c42f8d16ca4e3a83122799f57335111631aab0 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Tue, 30 Jun 2026 18:30:28 +0200 Subject: [PATCH] Disperse the 'GitHub issues for BPO users' page --- triage/github-bpo-faq.rst | 97 ++------------------------------------- triage/index.rst | 1 - triage/issue-tracker.rst | 85 ++++++++++++++++++++++++++++------ 3 files changed, 75 insertions(+), 108 deletions(-) diff --git a/triage/github-bpo-faq.rst b/triage/github-bpo-faq.rst index f4f8b16dd4..383bd7d53e 100644 --- a/triage/github-bpo-faq.rst +++ b/triage/github-bpo-faq.rst @@ -1,3 +1,5 @@ +:orphan: + .. _github-bpo-faq: .. _gh-faq: @@ -5,97 +7,8 @@ GitHub issues for BPO users =========================== -Here are some frequently asked questions 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 :ref:`tracker` -and :ref:`triaging` (specifically including :ref:`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 -`__. -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:: - -
- This is the summary text, click me to expand - - Here goes the long, long text. - It will be collapsed by default! -
- -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" `__. - -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 -:guilabel:`🔔 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 -:guilabel:`🔕 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 -`__. - -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 -`__ 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. +Here are some frequently asked questions about things you used to be able +to do on `bpo`_ that work differently in GitHub issues. Where did the "resolution" field go? ==================================== @@ -120,5 +33,3 @@ 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 diff --git a/triage/index.rst b/triage/index.rst index a054ad62f2..495d93917f 100644 --- a/triage/index.rst +++ b/triage/index.rst @@ -8,5 +8,4 @@ Issues and triaging issue-tracker triaging labels - github-bpo-faq triage-team diff --git a/triage/issue-tracker.rst b/triage/issue-tracker.rst index 31673d9435..77cc747911 100644 --- a/triage/issue-tracker.rst +++ b/triage/issue-tracker.rst @@ -5,7 +5,6 @@ Issue tracker ============= - Using the issue tracker ======================= @@ -13,8 +12,8 @@ If you think you have found a bug in Python, you can report it to the `issue tracker`_. The `issue tracker`_ is now hosted on GitHub, alongside the codebase and pull requests. Documentation bugs can also be reported there. -If you would like to file an issue about this devguide, please do so at the -`devguide repo`_. +If you would like to file an issue about this devguide, please do so in the +:github:`devguide repository `. .. note:: Prior to moving the issue tracker to GitHub, @@ -26,8 +25,7 @@ If you would like to file an issue about this devguide, please do so at the If you're familiar with ``bpo`` and would like to learn more about GitHub issues, please read this page, and the :ref:`triaging` page as they - provide good introductory material. There is also a :ref:`gh-faq` - document to answer some of the more popular questions. + provide good introductory material. Checking if a bug already exists -------------------------------- @@ -43,8 +41,16 @@ already been reported. Checking if the problem is an existing issue will: is needed To see if an issue already exists, search the bug database using the search box -above the list of bugs on the issues page. A form-based `advanced search`_ query -builder is also available on GitHub to help creating the text query you need. +above the list of bugs on the issues page. See :ref:`searching-gh-issues` +for more information. + +.. _searching-gh-issues: + +How to search issues? +--------------------- + +Use the `GitHub search syntax`_ or the interactive `advanced search`_ form +that generates search queries for you. Reporting an issue ------------------ @@ -89,6 +95,32 @@ 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. +Formatting issues and comments +------------------------------ + +There is a wonderful `beginner guide to 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:: + +
+ This is the summary text, click me to expand + + Here goes the long, long text. + It will be collapsed by default! +
+ + +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. + + Adding special links -------------------- @@ -107,17 +139,47 @@ If you want to subscribe yourself to an issue, click the :guilabel:`🔔 Subscri 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. +issues you create or comment on. + +Subscribe another person to the issue by tagging them in the comment with +``@username``. + + +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" `__. Tracking dependencies and duplicates ------------------------------------ +.. XXX These no longer work, the feature has been retired. + 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 `_. +What on earth is a "mannequin"? +------------------------------- + +For issues migrated to GitHub from `bpo`_ where the authors or commenters +are not core team members, we opted not to link to their GitHub accounts +directly. Users not in the `python organization on GitHub +`__ 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. + Disagreement with a resolution on the issue tracker =================================================== @@ -141,15 +203,10 @@ As a reminder, issues closed by a core developer have already been carefully considered. Please do not reopen a closed issue. An issue can be closed with reason either as ``complete`` or ``not planned``. -.. seealso:: - - `The Python issue tracker `_ - Where to report issues about Python. - .. _issue tracker: https://github.com/python/cpython/issues .. _advanced search: https://github.com/search/advanced -.. _devguide repo: https://github.com/python/devguide/issues +.. _GitHub search syntax: https://docs.github.com/en/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax .. _Roundup: https://www.roundup-tracker.org/ .. _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