Skip to content

Commit 79c42f8

Browse files
StanFromIrelandStanFromIreland
committed
Disperse the 'GitHub issues for BPO users' page
1 parent 3235043 commit 79c42f8

3 files changed

Lines changed: 75 additions & 108 deletions

File tree

‎triage/github-bpo-faq.rst‎

Lines changed: 4 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -1,101 +1,14 @@
1+
:orphan:
2+
13
.. _github-bpo-faq:
24
.. _gh-faq:
35

46
===========================
57
GitHub issues for BPO users
68
===========================
79

8-
Here are some frequently asked questions about how to do things in
9-
GitHub issues that you used to be able to do on `bpo`_.
10-
11-
Before you ask your own question, make sure you read :ref:`tracker`
12-
and :ref:`triaging` (specifically including :ref:`gh-labels`) as those
13-
pages include a lot of introductory material.
14-
15-
How to format my comments nicely?
16-
=================================
17-
18-
There is a wonderful `beginner guide to writing and formatting on GitHub
19-
<https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github>`__.
20-
Highly recommended.
21-
22-
One pro-tip we can sell you right here is that if you want to paste
23-
some longer log as a comment, attach a file instead (see how below).
24-
If you still insist on pasting it in your comment, do it like this::
25-
26-
<details>
27-
<summary>This is the summary text, click me to expand</summary>
28-
29-
Here goes the long, long text.
30-
It will be collapsed by default!
31-
</details>
32-
33-
How to attach files to an issue?
34-
================================
35-
36-
Drag them into the comment field, wait until the file uploads, and GitHub
37-
will automatically put a link to your file in your comment text.
38-
39-
How to link to file paths in the repository when writing comments?
40-
==================================================================
41-
42-
Use Markdown links. If you link to the default GitHub path, the file
43-
will link to the latest current version on the given branch.
44-
45-
You can get a permanent link to a given revision of a given file by
46-
`pressing "y" <https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files>`__.
47-
48-
How to do advanced searches?
49-
============================
50-
51-
Use the `GitHub search syntax`_ or the interactive `advanced search`_ form
52-
that generates search queries for you.
53-
54-
Where is the "nosy list"?
55-
=========================
56-
57-
Subscribe another person to the issue by tagging them in the comment with
58-
``@username``.
59-
60-
If you want to subscribe yourself to an issue, click the
61-
:guilabel:`🔔 Subscribe` button in the sidebar.
62-
63-
Similarly, if you were tagged by somebody else but
64-
decided this issue is not for you, you might click the
65-
:guilabel:`🔕 Unsubscribe` button in the sidebar.
66-
67-
There is no exact equivalent of the "nosy list" feature, so to preserve
68-
this information during the transfer, we list the previous members of
69-
this list in the first message on the migrated issue.
70-
71-
How to add issue dependencies?
72-
==============================
73-
74-
Add a checkbox list like this in the issue description::
75-
76-
- [x] #739
77-
- [ ] https://github.com/octo-org/octo-repo/issues/740
78-
- [ ] Add delight to the experience when all tasks are complete :tada:
79-
80-
then those will become sub-tasks on the given issue. Moreover, GitHub will
81-
automatically mark a task as complete if the other referenced issue is
82-
closed. More details in the `official GitHub documentation
83-
<https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists>`__.
84-
85-
What on earth is a "mannequin"?
86-
===============================
87-
88-
For issues migrated to GitHub from `bpo`_ where the authors or commenters
89-
are not core developers, we opted not to link to their GitHub accounts
90-
directly. Users not in the `python organization on GitHub
91-
<https://github.com/orgs/python/people>`__ might not like comments to
92-
appear under their name from an automated import. Others never linked GitHub on
93-
`bpo`_ in the first place so linking their account, if any, would be impossible.
94-
95-
In those cases a "mannequin" account is present to help follow the conversation
96-
that happened in the issue. In case the user did share their GitHub account
97-
name in their `bpo`_ profile, we use that. Otherwise, their classic `bpo`_
98-
username is used instead.
10+
Here are some frequently asked questions about things you used to be able
11+
to do on `bpo`_ that work differently in GitHub issues.
9912

10013
Where did the "resolution" field go?
10114
====================================
@@ -120,5 +33,3 @@ particularly useful outside of the change log.
12033

12134

12235
.. _bpo: https://bugs.python.org/
123-
.. _GitHub search syntax: https://docs.github.com/en/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax
124-
.. _advanced search: https://github.com/search/advanced

‎triage/index.rst‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,5 +8,4 @@ Issues and triaging
88
issue-tracker
99
triaging
1010
labels
11-
github-bpo-faq
1211
triage-team

‎triage/issue-tracker.rst‎

Lines changed: 71 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,15 @@
55
Issue tracker
66
=============
77

8-
98
Using the issue tracker
109
=======================
1110

1211
If you think you have found a bug in Python, you can report it to the
1312
`issue tracker`_. The `issue tracker`_ is now hosted on GitHub, alongside
1413
the codebase and pull requests. Documentation bugs can also be reported there.
1514

16-
If you would like to file an issue about this devguide, please do so at the
17-
`devguide repo`_.
15+
If you would like to file an issue about this devguide, please do so in the
16+
:github:`devguide repository <python/devguide>`.
1817

1918
.. note::
2019
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
2625

2726
If you're familiar with ``bpo`` and would like to learn more about GitHub
2827
issues, please read this page, and the :ref:`triaging` page as they
29-
provide good introductory material. There is also a :ref:`gh-faq`
30-
document to answer some of the more popular questions.
28+
provide good introductory material.
3129

3230
Checking if a bug already exists
3331
--------------------------------
@@ -43,8 +41,16 @@ already been reported. Checking if the problem is an existing issue will:
4341
is needed
4442

4543
To see if an issue already exists, search the bug database using the search box
46-
above the list of bugs on the issues page. A form-based `advanced search`_ query
47-
builder is also available on GitHub to help creating the text query you need.
44+
above the list of bugs on the issues page. See :ref:`searching-gh-issues`
45+
for more information.
46+
47+
.. _searching-gh-issues:
48+
49+
How to search issues?
50+
---------------------
51+
52+
Use the `GitHub search syntax`_ or the interactive `advanced search`_ form
53+
that generates search queries for you.
4854

4955
Reporting an issue
5056
------------------
@@ -89,6 +95,32 @@ and **Projects**. Those are filled by triagers and core
8995
developers and are covered in the :ref:`triaging` page. You don't need
9096
to worry about those when reporting issues as a Python user.
9197

98+
Formatting issues and comments
99+
------------------------------
100+
101+
There is a wonderful `beginner guide to writing and formatting on GitHub
102+
<https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github>`__.
103+
Highly recommended.
104+
105+
One pro-tip we can sell you right here is that if you want to paste
106+
some longer log as a comment, attach a file instead (see how below).
107+
If you still insist on pasting it in your comment, do it like this::
108+
109+
<details>
110+
<summary>This is the summary text, click me to expand</summary>
111+
112+
Here goes the long, long text.
113+
It will be collapsed by default!
114+
</details>
115+
116+
117+
How to attach files to an issue?
118+
--------------------------------
119+
120+
Drag them into the comment field, wait until the file uploads, and GitHub
121+
will automatically put a link to your file in your comment text.
122+
123+
92124
Adding special links
93125
--------------------
94126

@@ -107,17 +139,47 @@ If you want to subscribe yourself to an issue, click the :guilabel:`🔔 Subscri
107139
button in the sidebar. Similarly, if you were tagged by somebody else but
108140
decided this issue is not for you, click the :guilabel:`🔕 Unsubscribe`
109141
button in the sidebar. Note that you are automatically subscribed to
110-
issues you created.
142+
issues you create or comment on.
143+
144+
Subscribe another person to the issue by tagging them in the comment with
145+
``@username``.
146+
147+
148+
How to link to file paths in the repository when writing comments?
149+
------------------------------------------------------------------
150+
151+
Use Markdown links. If you link to the default GitHub path, the file
152+
will link to the latest current version on the given branch.
153+
154+
You can get a permanent link to a given revision of a given file by
155+
`pressing "y" <https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files>`__.
111156

112157
Tracking dependencies and duplicates
113158
------------------------------------
114159

160+
.. XXX These no longer work, the feature has been retired.
161+
115162
It is possible to use `checklists`_ to track dependencies or,
116163
in case of meta-issues, to link to the other related issues.
117164

118165
By writing :samp:`Duplicate of #{NNN}` in a comment, you can
119166
`mark issues and PRs as duplicates <duplicates_>`_.
120167

168+
What on earth is a "mannequin"?
169+
-------------------------------
170+
171+
For issues migrated to GitHub from `bpo`_ where the authors or commenters
172+
are not core team members, we opted not to link to their GitHub accounts
173+
directly. Users not in the `python organization on GitHub
174+
<https://github.com/orgs/python/people>`__ might not like comments to
175+
appear under their name from an automated import. Others never linked GitHub on
176+
`bpo`_ in the first place so linking their account, if any, would be impossible.
177+
178+
In those cases a "mannequin" account is present to help follow the conversation
179+
that happened in the issue. In case the user did share their GitHub account
180+
name in their `bpo`_ profile, we use that. Otherwise, their classic `bpo`_
181+
username is used instead.
182+
121183

122184
Disagreement with a resolution on the issue tracker
123185
===================================================
@@ -141,15 +203,10 @@ As a reminder, issues closed by a core developer have already been carefully
141203
considered. Please do not reopen a closed issue. An issue can be closed with
142204
reason either as ``complete`` or ``not planned``.
143205

144-
.. seealso::
145-
146-
`The Python issue tracker <issue tracker_>`_
147-
Where to report issues about Python.
148-
149206

150207
.. _issue tracker: https://github.com/python/cpython/issues
151208
.. _advanced search: https://github.com/search/advanced
152-
.. _devguide repo: https://github.com/python/devguide/issues
209+
.. _GitHub search syntax: https://docs.github.com/en/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax
153210
.. _Roundup: https://www.roundup-tracker.org/
154211
.. _Python Discourse: https://discuss.python.org/
155212
.. _autolinks: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls

0 commit comments

Comments
 (0)