Skip to content

Disperse the 'GitHub issues for BPO users' page #1850

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
StanFromIreland wants to merge 1 commit into
base: main
Choose a base branch
from
+75 −108
Open

Disperse the 'GitHub issues for BPO users' page #1850

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 4 additions & 93 deletions triage/github-bpo-faq.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,101 +1,14 @@
:orphan:

.. _github-bpo-faq:
.. _gh-faq:

===========================
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
<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
: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
<https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/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.
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?
====================================
Expand All @@ -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
1 change: 0 additions & 1 deletion triage/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,5 +8,4 @@ Issues and triaging
issue-tracker
triaging
labels
github-bpo-faq
triage-team
85 changes: 71 additions & 14 deletions triage/issue-tracker.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,16 +5,15 @@
Issue tracker
=============


Using the issue tracker
=======================

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 <python/devguide>`.

.. note::
Prior to moving the issue tracker to GitHub,
Expand All @@ -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
--------------------------------
Expand All @@ -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
------------------
Expand Down Expand Up @@ -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
<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.


Adding special links
--------------------

Expand All @@ -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" <https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files>`__.

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 <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
<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.


Disagreement with a resolution on the issue tracker
===================================================
Expand All @@ -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 <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
Expand Down
Loading