diff --git a/core-developers/committing.rst b/core-developers/committing.rst index 29cff328e..be223ba83 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -75,6 +75,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 493429fe6..0fcb7f588 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -7,32 +7,26 @@ 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 ====================== -* 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. +* 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 (: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 the issue is clearly invalid (unrelated to CPython, duplicate, spam, etc), + you can close it as "not planned". + +.. Remove note once python/core-workflow#460 is implemented + +.. note:: Some of these fields can only be set/edited by core developers. .. _helptriage: @@ -41,14 +35,13 @@ 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. 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 everything runs smoothly. Classifying Reports ------------------- @@ -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: 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 +* 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 linked pull request 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 * is a good solution to the problem it is trying to solve +* follows the style guides (:pep:`7`, :pep:`8`, :ref:`style-guide`, etc.) * 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 +* 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 +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 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. .. _advanced search: https://github.com/search/advanced