From 1b14292609ddc39db4561aa481681e7878419494 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Tue, 12 Jul 2022 04:21:33 +0200 Subject: [PATCH 1/7] Update the triage/triaging.rst page. --- core-developers/committing.rst | 2 + triage/triaging.rst | 78 ++++++++++++++++------------------ 2 files changed, 38 insertions(+), 42 deletions(-) diff --git a/core-developers/committing.rst b/core-developers/committing.rst index d4832ebbd2..9feffdda22 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -73,6 +73,8 @@ to enter the public source tree. Ask yourself the following questions: require a ``NEWS`` entry. (See the following section for more information.) +.. _news-entry: + Updating NEWS and What's New in Python -------------------------------------- diff --git a/triage/triaging.rst b/triage/triaging.rst index 493429fe6d..f909377812 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -14,25 +14,18 @@ directly without any assistance. Checklist for Triaging ====================== -* Read the issue comment(s). -* Review and set classification fields - - Title: should be concise with specifics which are helpful to someone - scanning a list of issue titles. (Optional, if possible) Add a - prefix at the start of the title to indicate the module, e.g. IDLE, - doc, or async. - - Type - - Stage - - Components: multiple items may be set - - Versions: set if known, leave blank if unsure. Multiple items may be set. -* Review and set process fields - - Status - - Superseder - - Assignees - - Nosy List - - Priority - - Keywords -* (Optional) Leave a brief comment about the proposed next action needed. If - there is a long message list, a summary can be very helpful. +* Check that the title is concise with specifics which are helpful to + someone scanning a list of issue titles. +* For pull request, ensure that the corresponding issue is added before + the title (``gh-NNNNN: ...``). +* Read the initial message and the comments. +* Set all the relevant :ref:`labels `. +* Where appropriate, you might set the "Assignees", "Reviewers", and + "Projects" fields. +* You might also leave a brief comment about the proposed next action needed. + If there is a long message list, a summary can be very helpful. + +Note: some of these fields can only be set/edited by core developers. .. _helptriage: @@ -41,7 +34,7 @@ Helping Triage Issues ===================== Once you know your way around how Python's source files are -structured and you are comfortable working with patches, a great way to +structured and you are comfortable with the workflow, a great way to contribute is to help triage issues. Do realize, though, that experience working on Python is needed in order to effectively help triage. @@ -62,44 +55,45 @@ For bugs, an issue needs to: These are things you can help with once you have experience developing for Python: -* try reproducing the bug: For instance, if a bug is not clearly explained - enough for you to reproduce it then there is a good chance a core developer +* try reproducing the bug: for instance, if a bug is not clearly explained + enough for you to reproduce it, then there is a good chance a core developer won't be able to either. -* see if the issue happens on a different Python version: It is always helpful +* see if the issue happens on a different Python version: it is always helpful to know if a bug not only affects the in-development version of Python, but whether it also affects other versions in maintenance mode. -* write a unit test: If the bug lacks a unit test that should end up in +* write a unit test: if the bug lacks a unit test that should end up in Python's test suite, having that written can be very helpful. -This is all helpful as it allows triagers (i.e., -:ref:`people with the Developer role on the issue tracker `) to -properly classify an issue so it can be handled by the right core developers in -a timely fashion. +This is all helpful as it allows members of the :ref:`triage team ` +to properly classify an issue so it can be handled by the right core developers +in a timely fashion. -Reviewing Patches ------------------ +Reviewing Pull Requests +----------------------- -If an issue has a pull request attached that has not been reviewed, you can help -by making sure the patch: +If an issue has a pull request attached that has not been reviewed, +you can help by making sure the pull request: * follows the style guides -* applies cleanly to an up-to-date clone +* doesn't have conflicts with the ``main`` branch * is a good solution to the problem it is trying to solve * includes proper tests * includes proper documentation changes -* submitter is listed in ``Misc/ACKS``, either already or the patch adds them +* includes a :ref:`NEWS entry ` (if needed) +* includes the author in ``Misc/ACKS``, either already or the patch adds them + +Doing all of this allows core developers and :ref:`triagers ` +to more quickly look for subtle issues that only people with extensive +experience working on Python's code base will notice. -Doing all of this allows core developers and :ref:`triagers` to more -quickly look for subtle issues that only people with extensive experience -working on Python's code base will notice. +See also :ref:`committing`. Finding an Issue You Can Help With ---------------------------------- -If you want to help triage issues, you might also want to search for issues -in modules which you have a working knowledge. Search for the name of a module -in the issue tracker or use the `advanced search`_ query builder to search for -specific kinds of issues (e.g. the "Windows" label if you are a Windows -developer, "Extension Modules" if you are familiar with C, etc.). +If you want to help with triaging, you might also want to search for issues +in modules which you have a working knowledge. Search for the name of a +module in the issue tracker, filter by label, or use the `advanced search`_ +to find these issues. .. _advanced search: https://github.com/search/advanced From e4f4a77b5adcbd761b453edbf522cf135ea937c0 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Sat, 6 Aug 2022 20:02:56 +0200 Subject: [PATCH 2/7] Mention the `triaged` label + more tweaks. --- triage/triaging.rst | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/triage/triaging.rst b/triage/triaging.rst index f909377812..3aeb60a9e3 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -7,9 +7,6 @@ Triaging an Issue This section of the devguide documents the :ref:`issue tracker ` for users and developers. -Contributors with the Triager role on the issue tracker can triage issues -directly without any assistance. - Checklist for Triaging ====================== @@ -24,6 +21,8 @@ Checklist for Triaging "Projects" fields. * You might also leave a brief comment about the proposed next action needed. If there is a long message list, a summary can be very helpful. +* Finally, you can set the `triaged` label (unless you want other triagers + to take a look). Note: some of these fields can only be set/edited by core developers. @@ -40,8 +39,7 @@ working on Python is needed in order to effectively help triage. Around the clock, new issues are being opened on the :ref:`issue tracker ` and existing issues are being updated. Every issue needs to be -triaged to make sure various things are in proper order. Even without special -privileges you can help with this process. +triaged to make sure various things are in proper order. Classifying Reports ------------------- @@ -55,13 +53,13 @@ For bugs, an issue needs to: These are things you can help with once you have experience developing for Python: -* try reproducing the bug: for instance, if a bug is not clearly explained +* Try reproducing the bug: for instance, if a bug is not explained clearly enough for you to reproduce it, then there is a good chance a core developer won't be able to either. -* see if the issue happens on a different Python version: it is always helpful +* See if the issue happens on a different Python version: it is always helpful to know if a bug not only affects the in-development version of Python, but whether it also affects other versions in maintenance mode. -* write a unit test: if the bug lacks a unit test that should end up in +* Write a unit test: if the bug lacks a unit test that should end up in Python's test suite, having that written can be very helpful. This is all helpful as it allows members of the :ref:`triage team ` @@ -71,16 +69,16 @@ in a timely fashion. Reviewing Pull Requests ----------------------- -If an issue has a pull request attached that has not been reviewed, +If an issue has a linked pull request that has not been reviewed, you can help by making sure the pull request: -* follows the style guides -* doesn't have conflicts with the ``main`` branch * is a good solution to the problem it is trying to solve +* follows the style guides * includes proper tests * includes proper documentation changes * includes a :ref:`NEWS entry ` (if needed) * includes the author in ``Misc/ACKS``, either already or the patch adds them +* doesn't have conflicts with the ``main`` branch Doing all of this allows core developers and :ref:`triagers ` to more quickly look for subtle issues that only people with extensive From 19db21024984321d199276bd6f300be11866062b Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Sat, 6 Aug 2022 20:04:39 +0200 Subject: [PATCH 3/7] Fix markup. --- triage/triaging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/triage/triaging.rst b/triage/triaging.rst index 3aeb60a9e3..214b6954eb 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -21,7 +21,7 @@ Checklist for Triaging "Projects" fields. * You might also leave a brief comment about the proposed next action needed. If there is a long message list, a summary can be very helpful. -* Finally, you can set the `triaged` label (unless you want other triagers +* Finally, you can set the ``triaged`` label (unless you want other triagers to take a look). Note: some of these fields can only be set/edited by core developers. From e928c5713bfe12d1fdb73302966f335a36c9e7cb Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Fri, 7 Oct 2022 07:24:10 +0200 Subject: [PATCH 4/7] Add a link to the `triaged` label. --- triage/triaging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/triage/triaging.rst b/triage/triaging.rst index 214b6954eb..a406b6297d 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -21,7 +21,7 @@ Checklist for Triaging "Projects" fields. * You might also leave a brief comment about the proposed next action needed. If there is a long message list, a summary can be very helpful. -* Finally, you can set the ``triaged`` label (unless you want other triagers +* Finally, you can set the :gh-label:`triaged` label (unless you want other triagers to take a look). Note: some of these fields can only be set/edited by core developers. From 034b1a32a21ad1c137a764560a5db9634781e444 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Sat, 8 Oct 2022 02:09:14 +0200 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: C.A.M. Gerlach --- triage/triaging.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/triage/triaging.rst b/triage/triaging.rst index a406b6297d..41dfafcaf1 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -11,18 +11,18 @@ users and developers. Checklist for Triaging ====================== -* Check that the title is concise with specifics which are helpful to - someone scanning a list of issue titles. -* For pull request, ensure that the corresponding issue is added before +* Check that the title is reasonably concise, while including enough specifics + so that those scanning the list of issues can quickly identify its topic. +* For pull requests, ensure that the corresponding issue is added before the title (``gh-NNNNN: ...``). * Read the initial message and the comments. * Set all the relevant :ref:`labels `. -* Where appropriate, you might set the "Assignees", "Reviewers", and - "Projects" fields. +* Where appropriate, set the :guilabel:`Assignees`, + :guilabel`Reviewers`, and :guilabel:`Project` fields. * You might also leave a brief comment about the proposed next action needed. If there is a long message list, a summary can be very helpful. -* Finally, you can set the :gh-label:`triaged` label (unless you want other triagers - to take a look). +* If instead the issue is invalid (can't reproduce, duplicate, etc.), + you can close it as "not planned". Note: some of these fields can only be set/edited by core developers. @@ -39,7 +39,7 @@ working on Python is needed in order to effectively help triage. Around the clock, new issues are being opened on the :ref:`issue tracker ` and existing issues are being updated. Every issue needs to be -triaged to make sure various things are in proper order. +triaged to make sure everything runs smoothly. Classifying Reports ------------------- @@ -53,7 +53,7 @@ For bugs, an issue needs to: These are things you can help with once you have experience developing for Python: -* Try reproducing the bug: for instance, if a bug is not explained clearly +* Try reproducing the bug: if it is not explained clearly enough for you to reproduce it, then there is a good chance a core developer won't be able to either. * See if the issue happens on a different Python version: it is always helpful From 5bd2948f7bef6b05143fdc248d02be37415976ea Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Sat, 8 Oct 2022 02:19:11 +0200 Subject: [PATCH 6/7] Address more review comments. --- triage/triaging.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/triage/triaging.rst b/triage/triaging.rst index 41dfafcaf1..c7fa0c241b 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -11,14 +11,14 @@ users and developers. Checklist for Triaging ====================== +* Read the initial message and the comments. * Check that the title is reasonably concise, while including enough specifics so that those scanning the list of issues can quickly identify its topic. * For pull requests, ensure that the corresponding issue is added before the title (``gh-NNNNN: ...``). -* Read the initial message and the comments. * Set all the relevant :ref:`labels `. -* Where appropriate, set the :guilabel:`Assignees`, - :guilabel`Reviewers`, and :guilabel:`Project` fields. +* Where appropriate, set the :guilabel:`Assignees`, :guilabel:`Reviewers`, + :guilabel:`Project` fields, and possibly @mention relevant people. * You might also leave a brief comment about the proposed next action needed. If there is a long message list, a summary can be very helpful. * If instead the issue is invalid (can't reproduce, duplicate, etc.), @@ -73,7 +73,7 @@ If an issue has a linked pull request that has not been reviewed, you can help by making sure the pull request: * is a good solution to the problem it is trying to solve -* follows the style guides +* follows the style guides (:pep:`7`, :pep:`8`, :ref:`style-guide`, etc.) * includes proper tests * includes proper documentation changes * includes a :ref:`NEWS entry ` (if needed) From f530bca3b095c64f065dacf7af013817d075aad3 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Sat, 8 Oct 2022 08:46:45 +0200 Subject: [PATCH 7/7] Apply suggestions from code review Co-authored-by: C.A.M. Gerlach --- triage/triaging.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/triage/triaging.rst b/triage/triaging.rst index c7fa0c241b..0fcb7f5889 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -15,16 +15,18 @@ Checklist for Triaging * Check that the title is reasonably concise, while including enough specifics so that those scanning the list of issues can quickly identify its topic. * For pull requests, ensure that the corresponding issue is added before - the title (``gh-NNNNN: ...``). + the title (:samp:`gh-NNNNN: {Title}`). * Set all the relevant :ref:`labels `. * Where appropriate, set the :guilabel:`Assignees`, :guilabel:`Reviewers`, :guilabel:`Project` fields, and possibly @mention relevant people. * You might also leave a brief comment about the proposed next action needed. If there is a long message list, a summary can be very helpful. -* If instead the issue is invalid (can't reproduce, duplicate, etc.), +* If the issue is clearly invalid (unrelated to CPython, duplicate, spam, etc), you can close it as "not planned". -Note: some of these fields can only be set/edited by core developers. +.. Remove note once python/core-workflow#460 is implemented + +.. note:: Some of these fields can only be set/edited by core developers. .. _helptriage: @@ -90,7 +92,7 @@ Finding an Issue You Can Help With ---------------------------------- If you want to help with triaging, you might also want to search for issues -in modules which you have a working knowledge. Search for the name of a +in modules for which you have a working knowledge. Search for the name of a module in the issue tracker, filter by label, or use the `advanced search`_ to find these issues.