Document using Github issues as the issue tracker #814

ambv · 2022-02-18T20:40:35Z

This change should be landed once issues are migrated from BPO to Github issues. Some information here is based on psf/gh-migration#13 and PEP 588.

The bulk is in tracker.rst and triaging.rst. Since they must make sense in their entirety, I temporarily deleted the old versions of those files and created new ones so that they can be reviewed without confusing diffs.

JelleZijlstra · 2022-02-18T21:26:32Z

gh-labels.rst

+    Used for PRs that haven't been reviewed by anyone yet.
+
+awaiting core review
+    Used for PRs that have at least one core developer listed in the


Not sure this is right. I see this label being autoapplied either when:

A non-core dev has reviewed the PR (even if they requested changes)

Or when the PR is authored by a core dev

I see this label being autoapplied either when:

A non-core dev has reviewed the PR (even if they requested changes)
Or when the PR is authored by a core dev

I confirm that this is how bedevere automatically applies the awaiting core review label.

JelleZijlstra · 2022-02-18T21:26:52Z

gh-labels.rst

+    The PR author made requested changes, and they are waiting for review.
+
+awaiting merge
+    A triager or core developer issued an approving review. The PR


Triager review doesn't trigger this label

Suggested change

A triager or core developer issued an approving review. The PR

A core developer issued an approving review. The PR

The sentence sounds weird. Perhaps it can just say:
"The PR has been approved by a core developer and is ready to merge"

I tried to avoid passive voice. All in vain!

Mariatta · 2022-02-18T22:24:34Z

index.rst

@@ -304,8 +304,8 @@ Full Table of Contents
   documenting
   silencewarnings
   fixingissues
-   tracker
-   triaging
+   tracker2


Just curious of the renaming from tracker to tracker2. Is this because we're keeping a backup of the old tracker document? Does 2 means like version 2 or something?

I think @ambv did that so it's easier to review the new document as a whole, because it's nearly a full rewrite. Unfortunately, GitHub in the review pane shows a diff between tracker and tracker2 anyway.

Yes, @JelleZijlstra is right. Git itself is trying to be too smart here but fortunately I foresaw this and the deletion is a separate commit. So if you only look at 699f8f1, it reads easier.

Mariatta · 2022-02-18T22:31:02Z

tracker2.rst



 .. _devrole:

-Gaining the "Developer" Role on the Issue Tracker
-=================================================
+Gaining the "Triager" Role on the Issue Tracker


I think we can remove this whole section completely. I believe this was specific to the role on b.p.o.

For becoming a member of the Python Triage team on GitHub, it was already covered in a different page: https://devguide.python.org/triaging/#becoming-a-member-of-the-python-triage-team

ezio-melotti

I left a few comments but haven't fully reviewed the triaging2 page, since it shows up as a whole new file and it's hard to tell what changed from the original page. It might be better to just edit the original pages instead of creating new files.

I think it would be better to divide the FAQ/docs in 2-3 sections:

the migration (what has been transferred, how bpo things map to GitHub, etc.)
GitHub issues in general (general guidelines and tips about using GitHub issues)
CPython-specific guidelines (labels, templates, workflows, actions, etc.)

Currently the FAQs are a mix of the first two, but it would be better to separate them. For example, the "Where is the 'nosy list'?" explains how to subscribe to issues. This is useful for bpo users, but also for new users, except that they wouldn't know what the "nosy list" is and might have a hard time finding out that answer.

With two separate sections you could have "How do I subscribe/follow an issue?" FAQ in the "Using GitHub" section and then a "Where is the 'nosy list'?" FAQ in the "GitHub for BPO users" section that links to it.

Some CPython-specific guidelines are already covered in the triaging and tracker pages instead, so they don't necessarily have to be in the FAQ (even though there could be FAQs linking to the relevant sections, or some sections could be converted into FAQ).

ezio-melotti · 2022-02-19T00:07:55Z

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


The label is currently called docs, even though there is a type-documentation for PRs, so we might end up merging them at some point.

Suggested change

.. _documentation issues: https://github.com/python/cpython/issues?q=is%3Aissue+is%3Aopen+label%3Adocumentation

.. _documentation issues: https://github.com/python/cpython/issues?q=is%3Aissue+is%3Aopen+label%3Adocs

ezio-melotti · 2022-02-19T00:07:55Z

gh-faq.rst

+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>`_.


It might be worth mentioning how to link a section of a file. I personally do this much often than linking whole files.

This is the relevant doc: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-a-permanent-link-to-a-code-snippet

ezio-melotti · 2022-02-19T00:07:55Z

gh-faq.rst

@@ -0,0 +1,100 @@
+Github issues for BPO users


This (and all other occurrences should be spelled GitHub

Suggested change

Github issues for BPO users

GitHub issues for BPO users

ezio-melotti · 2022-02-19T00:07:55Z

gh-faq.rst

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


This could mention that the nosy list is lost during the migration, but a list of nosy list users is listed at the top of each imported issue.

ezio-melotti · 2022-02-19T00:07:55Z

triaging2.rst

@@ -0,0 +1,362 @@
+.. _triaging:


The tracker2.rst page is seen as a rename of tracker.rst, but this is seen as a completely separate page and the diff is not very helpful. Is there any reason for renaming the pages and deleting the originals rather than just editing them?

Sadly git does not track renames, but it tries to guess when computing diffs. See comment above by ambv, there’s a commit with only the new file added that’s easier to read.

ezio-melotti · 2022-02-19T00:07:55Z

tracker2.rst

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


Suggested change

the bug, unless you changed your Github notification settings.

the issue, unless you changed your Github notification settings.

ezio-melotti · 2022-02-19T00:07:55Z

tracker2.rst

+* **Tests**: something is wrong with CPython's suite of regression tests;
+* **Discuss**: you'd like to learn more about Python, discuss ideas for
+  possible changes to future Python versions, track core development
+  discussions, or join a specific special-interest group.


Are these already in place?

ezio-melotti · 2022-02-19T00:07:55Z

triaging2.rst

+
+Choosing certain components, such as `Documentation`, may cause the issue to
+be auto-assigned, i.e. the issue tracker may automatically fill in the
+`Assignees`_ field after you add the label.


GitHub doesn't do this, so we should either fix the issue or remove the paragraph.

The whole section still seems modeled after BPO and partially overlapping with the gh-labels page -- are you planning to make other changes?

jacobtylerwalls · 2022-02-23T04:58:58Z

gh-labels.rst

+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. This label
+    helps core developers quickly identify PRs that are candidates for closure
+    or require a ping to the author.


I think stale is just simply no activity, not awaiting changes. No activity might include waiting for an initial review (or a wontfix, as the case may be).

ambv added 2 commits Feb 18, 2022

Document using Github issues as the issue tracker

699f8f1

Temporarily delete tracker.rst and triaging.rst

b3bc6ef

the-knights-who-say-ni added the CLA signed label Feb 18, 2022

JelleZijlstra reviewed Feb 18, 2022

View changes

Mariatta reviewed Feb 18, 2022

View changes

ezio-melotti requested changes Feb 19, 2022

View changes

jacobtylerwalls reviewed Feb 23, 2022

View changes

ezio-melotti mentioned this pull request Mar 8, 2022

Add a banner after the migration. psf/bpo-tracker-cpython#12

Open

ezio-melotti mentioned this pull request Mar 11, 2022

Migration and risk management plans psf/gh-migration#13

Open

46 tasks

python / devguide Public

Document using Github issues as the issue tracker #814

Document using Github issues as the issue tracker #814

ambv commented Feb 18, 2022

JelleZijlstra Feb 18, 2022

Mariatta Feb 18, 2022

JelleZijlstra Feb 18, 2022

JelleZijlstra Feb 18, 2022

Mariatta Feb 18, 2022

ambv Feb 18, 2022

Mariatta Feb 18, 2022

JelleZijlstra Feb 18, 2022

ambv Feb 18, 2022

Mariatta Feb 18, 2022

ezio-melotti left a comment

ezio-melotti Feb 19, 2022

ezio-melotti Feb 19, 2022

ezio-melotti Feb 19, 2022

ezio-melotti Feb 19, 2022

ezio-melotti Feb 19, 2022

merwok Feb 21, 2022

ezio-melotti Feb 19, 2022

ezio-melotti Feb 19, 2022

ezio-melotti Feb 19, 2022

jacobtylerwalls Feb 23, 2022

	A triager or core developer issued an approving review. The PR
	A core developer issued an approving review. The PR

	.. _documentation issues: https://github.com/python/cpython/issues?q=is%3Aissue+is%3Aopen+label%3Adocumentation
	.. _documentation issues: https://github.com/python/cpython/issues?q=is%3Aissue+is%3Aopen+label%3Adocs

	the bug, unless you changed your Github notification settings.
	the issue, unless you changed your Github notification settings.

python / devguide Public

Document using Github issues as the issue tracker #814

Are you sure you want to change the base?

Document using Github issues as the issue tracker #814

Conversation

ambv commented Feb 18, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ezio-melotti left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment