From ee691359e6ac5d0eb985365c5c6cf12275779191 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Sun, 7 Aug 2022 00:12:04 +0200 Subject: [PATCH 01/21] Update the triage/labels.rst page. --- core-developers/committing.rst | 1 + getting-started/pull-request-lifecycle.rst | 4 +- getting-started/setup-building.rst | 1 + triage/labels.rst | 251 ++++++++------------- triage/triage-team.rst | 18 +- 5 files changed, 105 insertions(+), 170 deletions(-) diff --git a/core-developers/committing.rst b/core-developers/committing.rst index d4832ebbd2..d327e5bef6 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -72,6 +72,7 @@ to enter the public source tree. Ask yourself the following questions: be added as well. Changes that affect only documentation generally do not require a ``NEWS`` entry. (See the following section for more information.) +.. _news-entry: Updating NEWS and What's New in Python -------------------------------------- diff --git a/getting-started/pull-request-lifecycle.rst b/getting-started/pull-request-lifecycle.rst index 5f2a4262db..928b36dc7d 100644 --- a/getting-started/pull-request-lifecycle.rst +++ b/getting-started/pull-request-lifecycle.rst @@ -386,6 +386,9 @@ on how to properly add the co-author info. See also :ref:`Applying a Patch to Git `. + +.. _reviewing-prs: + Reviewing ========= @@ -410,7 +413,6 @@ thus iterate until a satisfactory solution has emerged. .. _how-to-review-a-pull-request: - How to Review a Pull Request ---------------------------- diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index c59c1e544a..ba9c272596 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -544,6 +544,7 @@ support. For editors and tools which the core developers have felt some special comment is needed for coding *in* Python, see :ref:`resources`. +.. _directory-structure: Directory structure =================== diff --git a/triage/labels.rst b/triage/labels.rst index 78a5ac9b52..76ee68bcc0 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -10,190 +10,125 @@ Many labels are shared for both use cases, while some are dedicated only to one. Below is a possibly inexhaustive list, but it should get you going. For a full list, see `here `_. -General purpose labels -====================== -type-behavior - Used for issues/PRs that address unintentional behavior, but do not - pose significant security concerns. Generally, bugfixes will be attached - to a specific issue where the unintended behavior was first reported. +Type labels +=========== -type-documentation - Used for issues/PRs that exclusively involve changes to - the documentation. Documentation includes ``*.rst`` files, docstrings, - and code comments. +These labels are used to specify the type of issue: -type-enhancement - Used for issues/PRs that provide additional functionality - or capabilities beyond the existing specifications. +* ``type-bug``: for unexpected behaviors, bugs, or errors (not hard crashes). +* ``type-crash``: for hard crashes of the interpreter, possibly with a + core dump. +* ``type-feature``: for feature requests or enhancements. +* ``type-security``: for security issues. -type-performance - Used for issues/PRs that provide performance optimizations. +Since most PRs have an associated issue, it is not necessary to apply these +labels to PRs -type-security - Used for issues/PRs that involve critical security issues. Less severe - security concerns can instead use the type-bugfix label. -type-tests - Used for issues/PRs that exclusively involve changes to the tests. +Component labels +================ -OS-Mac / OS-Windows - Used for issues/PRs involving changes which only have an effect upon - a specific operating system. +These labels are mostly used to specify which :ref:`part of the codebase +` is affected by the issue/PR: -spam - Used for issues/PRs that don't include enough eggs or bacon. -Labels specific to issues -========================= +* ``stdlib``: for standard library modules in the :file:`Lib` directory + (written in Python). +* ``extension-modules``: for standard library modules in the :file:`Modules` + directory (written in C). +* ``interpreter-core``: for changes related to the interpreter core in the + :file:`Objects`, :file:`Python`, :file:`Grammar`, and :file:`Parser` dirs + (written mostly in C). +* ``docs``: for documentation in the :file:`Doc` directory (written in + reStructuredText), docstrings, and code comments. +* ``tests``: for tests in the :file:`Lib/test` directory (written in Python) + and changes other related to tests, ``unittest``, or ``doctests``. -Priority --------- -release-blocker - The highest priority of an issue. If unaddressed, will cause the - release manager to hold releasing a new version of Python. +Expert labels +============= + +These labels are used to specify the area of expertise required to address +the issue/PR. This includes both specific modules/packages and generic +interest areas. -deferred-blocker - A release blocker that was pushed one or more releases into the - future. Possibly a temporary workaround was employed, or the version - of Python the issue is affecting is still in alpha or beta stages - of development. +Adding these labels is also a way to notify the relevant experts, since +they are encouraged to subscribe to these labels. Depending on the label, +this might also automatically add the issue to a GitHub project. -Component ---------- +You can see the `full list of expert labels on GitHub +`_. -library - Used for issues involving Python modules in the ``Lib/`` dir. -docs - Used for issues involving documentation in the ``Doc/`` dir. +OS labels +========= -interpreter-core - Used for issues in interpreter core (``Objects/``, ``Python/``, - ``Grammar/``, and ``Parser/`` dirs). +These labels are used to specify which operating systems are affected. +Since most issues either affect all systems or are specific to Unix, +the only available labels are ``OS-windows``, ``OS-mac``, and ``OS-freebsd``. -extension-modules - Used for issues involving C modules in the ``Modules/`` dir. -tests - Used for issues involving only Python's regression test suite, i.e. - files in the ``Lib/test/`` dir. +Version labels +============== + +These labels are used to indicate which versions of Python are affected. +The available version labels (with the form :samp:`3.{x}`) are updated +whenever new major releases are created or retired. -Other ------ -new - Denotes that the issue hasn't been looked at by triagers or core - developers yet. +Other labels +============ -easy - Denotes that the issue is a good candidate for a newcomer to address. +* ``triaged``: for issue has been accepted as valid by a triager. +* ``easy``: for issues that are considered easy. +* ``build``/``performance``: for issues related respectively to the + build process and performances. +* ``release-blocker``/``deferred-blocker``: for issues/PRs that, unless + fixed, will hold the current or next release respectively. +* ``pending``: for issues/PRs that will be closed unless further feedback + is provided. +* ``stale``: for issues/PRs that have been inactive for a while. +* ``sprint``: used for easier filtering of issues/PRs being worked on during + official sprints. Labels specific to PRs ====================== -DO-NOT-MERGE - Used on PRs to prevent miss-islington from being able - to automatically merge the pull request. This label is appropriate when a PR - has a non-trivial conflict with the branch it is being merged into. - -expert-asyncio - Used for PRs which involve changes to the asyncio module - or other asynchronous frameworks that utilize it. - -invalid - Used manually for PRs that do not meet basic requirements and - automatically added by bedevere when PR authors attempt to merge maintenance - branches into the main branch. During events such as the October - Hacktoberfest, this label will prevent the PR from counting toward the - author's contributions. - -needs backport to X.Y - Used for PRs which are appropriate to backport to - branches prior to main. Generally, backports to the maintenance branches - are primarily bugfixes and documentation clarifications. Backports to the - security branches are strictly reserved for PRs involving security fixes, such as - crashes, privilege escalation, and DoS. The use of this label will cause - miss-islington to attempt to automatically merge the PR into the branches - specified. - -skip issue - Used for PRs which involve trivial changes, such as typo fixes, - comment changes, and section rephrases. The majority of PRs require - an issue to be attached to, but if there are no code changes and the - section being modified retains the same meaning, this label might be - appropriate. - -skip news - Similar to the skip issue label, this label is used for PRs which - involve trivial changes, backports, or already have a relevant news entry - in another PR. Any potentially impactful changes should have a - corresponding news entry, but for trivial changes it's commonly at the - discretion of the PR author if they wish to opt-out of making one. - -sprint - Used for PRs authored during an in-person sprint, such as - at PyCon, EuroPython, or other official Python events. The label is - used to prioritize the review of those PRs during the sprint. - -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, or when the - reviewer is unresponsive. This label helps core developers quickly identify - PRs that are candidates for closure or require a ping to the author or - reviewer. - -awaiting review - Used for PRs that haven't been reviewed by anyone yet. - -awaiting core review - Used when the PR is authored by a core developer or when a non-core - developer has reviewed the PR, even if they requested changes. - Note that reviewers could have been added manually by a triager or core - developer, or included automatically through use of the `CODEOWNERS - `_ - file. - -awaiting changes - A reviewer required changes to proceed with the PR. - -awaiting change review - The PR author made requested changes, and they are waiting for review. - -awaiting merge - The PR has been approved by a core developer and is ready to merge. - -test-with-buildbots - Used on PRs to test the latest commit with the buildbot fleet. Generally for - PRs with large code changes requiring more testing before merging. This - may take multiple hours to complete. Triagers can also stop a stuck build - using the web interface. - - -.. _github-pr-labels: - -GitHub Labels for PRs -===================== - -An important component of triaging PRs for the CPython repo involves -appropriately categorizing them through the usage of labels. For this -purpose we're using :ref:`gh-labels`. - -Applying labels for Issues -========================== - -The major elements found in an issue report include: - -* Classification (including *Title*) - Metadata that lets us categorize - the issue. Apart from the *Title* field, we use some *type-*, *component-*, and - *version-* specific labels. -* Process - These fields indicate the state of the issue and its progress - toward resolution. The fields are *Status* (open/closed), *Assignees*, - *Comment*, as well as *priority-* and *keyword-* specific labels. -* Messages -* History +The following labels only apply to PRs. They are either set automatically +by bots, or applied by humans to trigger specific bot behaviors. + +* ``DO-NOT-MERGE``: for PRs that shouldn't be merged in their current state. + It also prevents ``miss-islington`` from being able to automatically merge + the PR. +* :samp:`needs backport to {X.Y}`: used to indicate which branches the PR should be + backported to. Once the PR is merged, ``miss-islington`` will automatically + attempt to create backport PRs for the versions indicated by these labels. + See also :ref:`the status of the Python branches ` for a list + of branches and the type of PRs that can be backported to them. +* ``skip issue``: for trivial changes (such as typo fixes, comment changes, + and section rephrases) that don't require a corresponding issue. +* ``skip news``: for PRs that don't need a NEWS entry. The :ref:`news-entry` + section covers in details in which cases the NEWS entry can be skipped. +* :samp:`awaiting *`: these labels are applied and used by ``bedevere`` to + indicate the stage of a PR: + + * ``awaiting review``: the PR hasn't been reviewed and is waiting for a + review. + * ``awaiting core review``: a review by a core developer is needed. + * ``awaiting changes``: a reviewer requested changes to proceed with the PR. + * ``awaiting change review``: a review of the requested changes is needed. + * ``awaiting merge``: the PR has been approved by a core developer and is + ready to merge. + +* ``test-with-buildbots``: used to test the latest commit with the buildbot + fleet whenever more testing is required before merging. This may take + multiple hours to complete. Triagers can also stop a stuck build using + the web interface. + +.. TODO: delete most of what follows, since it seems specific for bpo. + Some things are still relevant, and should be moved elsewhere. Title ----- diff --git a/triage/triage-team.rst b/triage/triage-team.rst index 36994cd72e..a124681e2e 100644 --- a/triage/triage-team.rst +++ b/triage/triage-team.rst @@ -16,15 +16,11 @@ needed, to other repos such as devguide and core-workflow. Responsibilities include: -* PR/issue management - - Reviewing PRs - - Assisting contributors - - Notifying appropriate core developers -* Applying appropriate labels to PRs/Issues - - Skip news - - Skip issue - - Good first issue - - Other categorizations +* Classify issues and PRs +* Applying appropriate :ref:`labels ` to PRs/Issues +* Notifying appropriate core developers +* :ref:`Reviewing PRs ` +* Assisting contributors Although triagers have the power to close PRs, they should generally not do so without first consulting a core developer. By having triagers and core developers work together, @@ -46,9 +42,9 @@ following: If a triager has any doubt about whether to close a PR, they should consult a core developer before taking any action. -Triagers can also make use of the ``invalid`` and ``stale`` labels to suggest that a +Triagers can also make use of the ``pending`` and ``stale`` labels to suggest that a PR may be suitable for closure. For more information, see the -:ref:`GitHub PR labels ` section. +:ref:`GitHub PR labels ` section. Note that it is of paramount importance to treat every contributor to the Python project kindly and with respect. Regardless of whether they're entirely new From 8e3928ccc84a12c9bf855bfc5e3cff65c85079cd Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Sun, 25 Dec 2022 07:40:52 +0100 Subject: [PATCH 02/21] Remove duplicate label. --- core-developers/committing.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/core-developers/committing.rst b/core-developers/committing.rst index f66f0dcfa4..97ed6aea20 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -76,8 +76,6 @@ to enter the public source tree. Ask yourself the following questions: .. _news-entry: -.. _news-entry: - Updating NEWS and What's New in Python -------------------------------------- From f6ac25ce49ac1cf8d307c1f4d60ba839c16c31c5 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Sat, 24 Dec 2022 23:52:09 -0700 Subject: [PATCH 03/21] Use the `:gh-label:` role. --- core-developers/committing.rst | 1 + triage/labels.rst | 98 ++++++++++++++++++---------------- 2 files changed, 53 insertions(+), 46 deletions(-) diff --git a/core-developers/committing.rst b/core-developers/committing.rst index 97ed6aea20..be223ba83d 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -74,6 +74,7 @@ to enter the public source tree. Ask yourself the following questions: be added as well. Changes that affect only documentation generally do not 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/labels.rst b/triage/labels.rst index 07160a6129..01bd279c99 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -16,11 +16,12 @@ Type labels These labels are used to specify the type of issue: -* ``type-bug``: for unexpected behaviors, bugs, or errors (not hard crashes). -* ``type-crash``: for hard crashes of the interpreter, possibly with a +* :gh-label:`type-bug`: for unexpected behaviors, bugs, or errors + (not hard crashes). +* :gh-label:`type-crash`: for hard crashes of the interpreter, possibly with a core dump. -* ``type-feature``: for feature requests or enhancements. -* ``type-security``: for security issues. +* :gh-label:`type-feature`: for feature requests or enhancements. +* :gh-label:`type-security`: for security issues. Since most PRs have an associated issue, it is not necessary to apply these labels to PRs @@ -32,17 +33,17 @@ Component labels These labels are mostly used to specify which :ref:`part of the codebase ` is affected by the issue/PR: -* ``stdlib``: for standard library modules in the :file:`Lib` directory +* :gh-label:`stdlib`: for standard library modules in the :file:`Lib` directory (written in Python). -* ``extension-modules``: for standard library modules in the :file:`Modules` - directory (written in C). -* ``interpreter-core``: for changes related to the interpreter core in the - :file:`Objects`, :file:`Python`, :file:`Grammar`, and :file:`Parser` dirs +* :gh-label:`extension-modules`: for standard library modules in the + :file:`Modules` directory (written in C). +* :gh-label:`interpreter-core`: for changes related to the interpreter core in + the :file:`Objects`, :file:`Python`, :file:`Grammar`, and :file:`Parser` dirs (written mostly in C). -* ``docs``: for documentation in the :file:`Doc` directory (written in +* :gh-label:`docs`: for documentation in the :file:`Doc` directory (written in reStructuredText), docstrings, and code comments. -* ``tests``: for tests in the :file:`Lib/test` directory (written in Python) - and changes other related to tests, ``unittest``, or ``doctests``. +* :gh-label:`tests`: for tests in the :file:`Lib/test` directory (written in + Python) and changes other related to tests, ``unittest``, or ``doctests``. Expert labels @@ -65,7 +66,8 @@ OS labels These labels are used to specify which operating systems are affected. Since most issues either affect all systems or are specific to Unix, -the only available labels are ``OS-windows``, ``OS-mac``, and ``OS-freebsd``. +the only available labels are :gh-label:`OS-windows`, :gh-label:`OS-mac`, +and :gh-label:`OS-freebsd`. Version labels @@ -79,17 +81,17 @@ whenever new major releases are created or retired. Other labels ============ -* ``triaged``: for issue has been accepted as valid by a triager. -* ``easy``: for issues that are considered easy. -* ``build``/``performance``: for issues related respectively to the - build process and performances. -* ``release-blocker``/``deferred-blocker``: for issues/PRs that, unless - fixed, will hold the current or next release respectively. -* ``pending``: for issues/PRs that will be closed unless further feedback - is provided. -* ``stale``: for issues/PRs that have been inactive for a while. -* ``sprint``: used for easier filtering of issues/PRs being worked on during - official sprints. +* :gh-label:`triaged`: for issue has been accepted as valid by a triager. +* :gh-label:`easy`: for issues that are considered easy. +* :gh-label:`build`/:gh-label:`performance`: for issues related respectively + to the build process and performances. +* :gh-label:`release-blocker`/:gh-label:`deferred-blocker`: for issues/PRs + that, unless fixed, will hold the current or next release respectively. +* :gh-label:`pending`: for issues/PRs that will be closed unless further + feedback is provided. +* :gh-label:`stale`: for issues/PRs that have been inactive for a while. +* :gh-label:`sprint`: used for easier filtering of issues/PRs being worked on + during official sprints. @@ -99,33 +101,37 @@ Labels specific to PRs The following labels only apply to PRs. They are either set automatically by bots, or applied by humans to trigger specific bot behaviors. -* ``DO-NOT-MERGE``: for PRs that shouldn't be merged in their current state. - It also prevents ``miss-islington`` from being able to automatically merge - the PR. -* :samp:`needs backport to {X.Y}`: used to indicate which branches the PR should be - backported to. Once the PR is merged, ``miss-islington`` will automatically - attempt to create backport PRs for the versions indicated by these labels. +* :gh-label:`DO-NOT-MERGE`: for PRs that shouldn't be merged in their current + state. It also prevents ``miss-islington`` from being able to automatically + merge the PR. +* :samp:`needs backport to {X.Y}`: used to indicate which branches the PR + should be backported to. Once the PR is merged, ``miss-islington`` will + automatically attempt to create backport PRs for the versions indicated + by these labels. See also :ref:`the status of the Python branches ` for a list of branches and the type of PRs that can be backported to them. -* ``skip issue``: for trivial changes (such as typo fixes, comment changes, - and section rephrases) that don't require a corresponding issue. -* ``skip news``: for PRs that don't need a NEWS entry. The :ref:`news-entry` - section covers in details in which cases the NEWS entry can be skipped. +* :gh-label:`skip issue`: for trivial changes (such as typo fixes, comment + changes, and section rephrases) that don't require a corresponding issue. +* :gh-label:`skip news`: for PRs that don't need a NEWS entry. + The :ref:`news-entry` section covers in details in which cases the NEWS entry + can be skipped. * :samp:`awaiting *`: these labels are applied and used by ``bedevere`` to indicate the stage of a PR: - * ``awaiting review``: the PR hasn't been reviewed and is waiting for a - review. - * ``awaiting core review``: a review by a core developer is needed. - * ``awaiting changes``: a reviewer requested changes to proceed with the PR. - * ``awaiting change review``: a review of the requested changes is needed. - * ``awaiting merge``: the PR has been approved by a core developer and is - ready to merge. - -* ``test-with-buildbots``: used to test the latest commit with the buildbot - fleet whenever more testing is required before merging. This may take - multiple hours to complete. Triagers can also stop a stuck build using - the web interface. + * :gh-label:`awaiting review`: the PR hasn't been reviewed and is waiting + for a review. + * :gh-label:`awaiting core review`: a review by a core developer is needed. + * :gh-label:`awaiting changes`: a reviewer requested changes to proceed with + the PR. + * :gh-label:`awaiting change review`: a review of the requested changes + is needed. + * :gh-label:`awaiting merge`: the PR has been approved by a core developer + and is ready to merge. + +* :gh-label:`test-with-buildbots`: used to test the latest commit with + the buildbot fleet whenever more testing is required before merging. + This may take multiple hours to complete. Triagers can also stop + a stuck build using the web interface. .. TODO: delete most of what follows, since it seems specific for bpo. Some things are still relevant, and should be moved elsewhere. From 82dae3626dee63983cba594ad92ff2d0bd8f4df2 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Sun, 25 Dec 2022 00:44:04 -0700 Subject: [PATCH 04/21] Use the `:cpy-file:` role. --- triage/labels.rst | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/triage/labels.rst b/triage/labels.rst index 01bd279c99..315c1f948b 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -33,17 +33,18 @@ Component labels These labels are mostly used to specify which :ref:`part of the codebase ` is affected by the issue/PR: -* :gh-label:`stdlib`: for standard library modules in the :file:`Lib` directory - (written in Python). +* :gh-label:`stdlib`: for standard library modules in the :cpy-file:`Lib` + directory (written in Python). * :gh-label:`extension-modules`: for standard library modules in the - :file:`Modules` directory (written in C). + :cpy-file:`Modules` directory (written in C). * :gh-label:`interpreter-core`: for changes related to the interpreter core in - the :file:`Objects`, :file:`Python`, :file:`Grammar`, and :file:`Parser` dirs - (written mostly in C). -* :gh-label:`docs`: for documentation in the :file:`Doc` directory (written in - reStructuredText), docstrings, and code comments. -* :gh-label:`tests`: for tests in the :file:`Lib/test` directory (written in - Python) and changes other related to tests, ``unittest``, or ``doctests``. + the :cpy-file:`Objects`, :cpy-file:`Python`, :cpy-file:`Grammar`, + and :cpy-file:`Parser` dirs (written mostly in C). +* :gh-label:`docs`: for documentation in the :cpy-file:`Doc` directory + (written in reStructuredText), docstrings, and code comments. +* :gh-label:`tests`: for tests in the :cpy-file:`Lib/test` directory + (written in Python) and changes other related to tests, ``unittest``, + or ``doctests``. Expert labels From d51c0270a0b1f8d922d2a961f0ebb36b58d6c34f Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Sun, 25 Dec 2022 00:50:46 -0700 Subject: [PATCH 05/21] (Re)move (mostly) BPO-related info. --- triage/issue-tracker.rst | 40 ++++++- triage/labels.rst | 229 ++------------------------------------- 2 files changed, 44 insertions(+), 225 deletions(-) diff --git a/triage/issue-tracker.rst b/triage/issue-tracker.rst index 976cf1891f..943f56c68f 100644 --- a/triage/issue-tracker.rst +++ b/triage/issue-tracker.rst @@ -84,16 +84,43 @@ The submission form has only two fields that you need to fill: information as appropriate). In particular, *what version of Python* you were using. -Understanding the issue's progress and status ---------------------------------------------- +It is also acceptable to tag someone to if you think the issue +should be brought to their attention. Use the :ref:`experts` to know +who wants to be added to the nosy list for issues targeting specific areas. There is a number of additional fields like **Assignees**, **Labels**, **Projects**, and **Milestone**. Those are filled by triagers and core -developers, this is covered in the :ref:`triaging` page. You don't need +developers and are covered in the :ref:`triaging` page. You don't need 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. +Adding special links +-------------------- + +The following abbreviations can be used in a comment to generate a link: + +* :samp:`GH-{*}`: to link to another issue or PR; +* :samp:`PEP-{*}`: to link to a specific PEP; +* :samp:`BPO-{*}`: to link to a bugs.python.org issue; + +See also the `list of autolinks supported by GitHub `_. + +Following issues +---------------- + +If you want to subscribe yourself to an issue, click the *🔔 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 *🔕 Unsubscribe* +button in the sidebar. Note that you are automatically subscribed to +issues you created. + +Tracking dependencies and duplicates +------------------------------------ + +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 {#xxx}` in a comment, you can +`mark issues and PRs as duplicates `_. Disagreement With a Resolution on the Issue Tracker @@ -128,4 +155,7 @@ reason either as ``complete`` or ``not planned``. .. _devguide repo: https://github.com/python/devguide/issues .. _Roundup: https://roundup.sourceforge.io/ .. _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 +.. _checklists: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists +.. _duplicates: https://docs.github.com/en/issues/tracking-your-work-with-issues/marking-issues-or-pull-requests-as-a-duplicate .. _Core Development Discourse category: https://discuss.python.org/c/core-dev/23 diff --git a/triage/labels.rst b/triage/labels.rst index 315c1f948b..ee1068aa90 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -16,15 +16,18 @@ Type labels These labels are used to specify the type of issue: -* :gh-label:`type-bug`: for unexpected behaviors, bugs, or errors +* :gh-label:`type-bug`: for unexpected behaviors, bugs, or exceptions (not hard crashes). * :gh-label:`type-crash`: for hard crashes of the interpreter, possibly with a core dump. * :gh-label:`type-feature`: for feature requests or enhancements. + The `Ideas Discourse category`_ can be used to discuss enhancements + before filing an issue. * :gh-label:`type-security`: for security issues. + See also `Reporting security issues in Python`_. Since most PRs have an associated issue, it is not necessary to apply these -labels to PRs +labels to PRs. Component labels @@ -78,6 +81,9 @@ These labels are used to indicate which versions of Python are affected. The available version labels (with the form :samp:`3.{x}`) are updated whenever new major releases are created or retired. +See also :ref:`the branch status page ` +for a list of active branches. + Other labels ============ @@ -95,7 +101,6 @@ Other labels during official sprints. - Labels specific to PRs ====================== @@ -134,222 +139,6 @@ by bots, or applied by humans to trigger specific bot behaviors. This may take multiple hours to complete. Triagers can also stop a stuck build using the web interface. -.. TODO: delete most of what follows, since it seems specific for bpo. - Some things are still relevant, and should be moved elsewhere. - -Title ------ -A brief description of the issue. Review whether the title is too generic or -specifies an incorrect term or library. - -(Optional) Add a prefix at the start of the title to indicate the module, e.g. -IDLE, doc, or asyncio. - -Type ----- -Describes the type of issue. If an issue does not fit within any -specific type, please do not set a type. - -+----------------+----------------------------------------------------------+ -| Type | Description | -+================+==========================================================+ -| behavior | Unexpected behavior, result, or exception. Most bugs | -| | will have this type. This group also includes compile | -| | errors, and crashers. | -+----------------+----------------------------------------------------------+ -| enhancement | Issues that propose the addition of new functionality, | -| | such as new functions, classes, modules, or even new | -| | arguments for existing functions. Also used for | -| | improvements in the documentation, test suite and | -| | other refactorings. A good place to discuss enhancements | -| | prior to filing an issue is the | -| | `Ideas Discourse category`_. | -+----------------+----------------------------------------------------------+ -| performance | Situations where too much time is necessary to complete | -| | the task. For example, a common task now takes | -| | significantly longer to complete. This group also | -| | includes resource usage (e.g. too much memory needed) | -| | issues. | -+----------------+----------------------------------------------------------+ -| security | Issues that might have security implications. Report | -| | security vulnerabilities using the procedure found in | -| | the `Reporting security issues in Python`_ page on the | -| | python.org website. | -+----------------+----------------------------------------------------------+ - -Stage ------ -A needed next action to advance the issue. The *stage* on GitHub issues is -determined by presence of a linked PR and whether the issue is still open -or closed. It is the PR that holds code review-related labels. - -Components ----------- -The area or Python library affected by the issue. A single issue can apply -multiple component labels. - -One or more components may be selected for an issue: - -+-------------------+------------------------------------------------------+ -| Component | Description | -+===================+======================================================+ -| Documentation | The documentation in Doc_ (source used to build HTML | -| | docs for https://docs.python.org/). | -+-------------------+------------------------------------------------------+ -| Extension Modules | C modules in Modules_. | -+-------------------+------------------------------------------------------+ -| Interpreter Core | The interpreter core. | -| | The built-in objects in `Objects`_, the `Python`_, | -| | `Grammar`_ and `Parser`_ dirs. | -+-------------------+------------------------------------------------------+ -| Library (Lib) | Python modules in Lib_. | -+-------------------+------------------------------------------------------+ -| Tests | The unittest framework in `Lib/unittest`_ | -| | The doctest framework `Lib/doctest.py`_. | -| | The CPython tests in `Lib/test`_. | -| | The test runner in `Lib/test/regrtest.py`_. | -| | The test support utilities in `Lib/test/support`_. | -+-------------------+------------------------------------------------------+ - -Versions --------- -The known versions of Python that the issue affects and should be fixed for. - -Thus if an issue for a new feature is assigned for e.g., Python 3.8 but is not -applied before Python 3.8.0 is released, this label should be updated to say -``python-3.9`` as the version and drop ``python-3.8``. - -Priority --------- -What is the severity and urgency? - -+------------------+--------------------------------------------------------+ -| Priority | Description | -+==================+========================================================+ -| normal | The default value for most issues filed. | -+------------------+--------------------------------------------------------+ -| deferred blocker | The issue will not hold up the next release, *n*. It | -| | will be promoted to a *release blocker* for the | -| | following release, *n+1*. | -+------------------+--------------------------------------------------------+ -| release blocker | The issue **must** be fixed before *any* release is | -| | made, e.g., will block the next release even if it is | -| | an alpha release. | -+------------------+--------------------------------------------------------+ - -As a guideline, whether a bug is a *release blocker* for the current -:ref:`release schedule ` is decided by the release manager. -Triagers may recommend this priority and should notify the release manager by -tagging them in a comment using ``@username``. If needed, consult the -:ref:`release schedule ` and the release's associated PEP for the -release manager's name. - -Keywords --------- -Various informational flags about the issue. Multiple values are possible. - -+---------------+------------------------------------------------------------+ -| Keyword | Description | -+===============+============================================================+ -| easy | Fixing the issue should not take longer than a day for | -| | someone new to contributing to Python to solve. | -+---------------+------------------------------------------------------------+ - -Nosy List ---------- -A list of people who may be interested in an issue. - -This used to be a feature of the old issue tracker. On GitHub issues the -same effect is achieved by tagging people in a comment using ``@username``. - -It is acceptable to tag someone to if you think the issue should be brought to -their attention. Use the :ref:`experts` to know who wants to be added to the -nosy list for issues targeting specific areas. - -If you want to subscribe yourself to an issue, click the *🔔 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 *🔕 Unsubscribe* -button in the sidebar. - -Assignees ---------- -Who is expected to take the next step in resolving the issue. - -It is acceptable to assign an issue to someone if the issue cannot move -forward without their help, e.g., they need to make a technical decision to -allow the issue to move forward. Also consult the :ref:`experts` as certain -stdlib modules should always be assigned to a specific person. - -Note that in order to assign an issue to someone, that person **must** be -a team member, likely a Triager or a core developer. - -Dependencies ------------- -The issue requires the listed issue(s) to be resolved first before it can move -forward. This is achieved using checkbox lists in the initial issue description -comment. Long story short, if you add this:: - - - [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 -`_. - -Superseder ----------- -The issue is a duplicate of the listed issue(s). To make GitHub mark -an issue as duplicate, write "Duplicate of #xxxx" in a comment. - -Status ------- - -+---------------+------------------------------------------------------------+ -| Status | Description | -+===============+============================================================+ -| open | Issue is not resolved. | -+---------------+------------------------------------------------------------+ -| closed | The issue has been resolved (somehow). | -+---------------+------------------------------------------------------------+ - -Linked pull requests --------------------- -A link might be added manually using the cog icon next to this field. -Most commonly though, if the PR includes "Fixes #xxx" in its description, -the link will be added automatically. - -Generating Special Links in a Comment -===================================== -Using the following abbreviations in a comment will automatically generate -a link to relevant web pages. - -+-------------------------------------------------------------+-------------------------------------------------------+ -| Comment abbreviation | Description | -+=============================================================+=======================================================+ -| ``#``, | Links to the tracker issue or PR ```` (they | -| ``GH-`` | share the same sequence of integers on GitHub). | -+-------------------------------------------------------------+-------------------------------------------------------+ -| ``BPO-`` | Links to the old bug tracker at bugs.python.org. | -+-------------------------------------------------------------+-------------------------------------------------------+ -| a 10-, 11-, 12-, or 40-digit hex ```` | Indicates a Git changeset identifier and | -| | generates a link to changeset ```` on GitHub. | -+-------------------------------------------------------------+-------------------------------------------------------+ - -.. _Doc: https://github.com/python/cpython/tree/main/Doc/ -.. _Grammar: https://github.com/python/cpython/tree/main/Grammar/ -.. _Lib: https://github.com/python/cpython/tree/main/Lib/ -.. _Lib/doctest.py: https://github.com/python/cpython/blob/main/Lib/doctest.py -.. _Lib/test: https://github.com/python/cpython/tree/main/Lib/test/ -.. _Lib/test/regrtest.py: https://github.com/python/cpython/blob/main/Lib/test/regrtest.py -.. _Lib/test/support: https://github.com/python/cpython/tree/main/Lib/test/support/ -.. _Lib/unittest: https://github.com/python/cpython/tree/main/Lib/unittest/ -.. _Modules: https://github.com/python/cpython/tree/main/Modules/ -.. _Objects: https://github.com/python/cpython/tree/main/Objects/ -.. _Parser: https://github.com/python/cpython/tree/main/Parser/ -.. _Python: https://github.com/python/cpython/tree/main/Python/ + .. _Reporting security issues in Python: https://www.python.org/dev/security/ .. _Ideas Discourse category: https://discuss.python.org/c/ideas/6 From 579b6a5bd839b86a23929853aa5fe88e0f5320a4 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Mon, 26 Dec 2022 07:53:23 +0100 Subject: [PATCH 06/21] Apply suggestions from code review Co-authored-by: C.A.M. Gerlach --- triage/issue-tracker.rst | 20 ++++++++++---------- triage/labels.rst | 10 +++++----- triage/triage-team.rst | 4 ++-- 3 files changed, 17 insertions(+), 17 deletions(-) diff --git a/triage/issue-tracker.rst b/triage/issue-tracker.rst index 943f56c68f..a2069e2af8 100644 --- a/triage/issue-tracker.rst +++ b/triage/issue-tracker.rst @@ -84,11 +84,11 @@ The submission form has only two fields that you need to fill: information as appropriate). In particular, *what version of Python* you were using. -It is also acceptable to tag someone to if you think the issue -should be brought to their attention. Use the :ref:`experts` to know -who wants to be added to the nosy list for issues targeting specific areas. +You can tag someone, with :samp:`@{username}` in a comment, +if you think the issue should be brought to their attention. +Use the :ref:`experts` to know who wants to be tagged for specific areas. -There is a number of additional fields like **Assignees**, **Labels**, +There are a number of additional fields like **Assignees**, **Labels**, **Projects**, and **Milestone**. 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. @@ -98,18 +98,18 @@ Adding special links The following abbreviations can be used in a comment to generate a link: -* :samp:`GH-{*}`: to link to another issue or PR; -* :samp:`PEP-{*}`: to link to a specific PEP; -* :samp:`BPO-{*}`: to link to a bugs.python.org issue; +* :samp:`GH-{NNN}`: to link to another issue or PR; +* :samp:`PEP-{NNN}`: to link to a specific PEP; +* :samp:`BPO-{NNN}`: to link to a bugs.python.org issue; See also the `list of autolinks supported by GitHub `_. Following issues ---------------- -If you want to subscribe yourself to an issue, click the *🔔 Subscribe* +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 *🔕 Unsubscribe* +decided this issue is not for you, you might click the :guilabel:`🔕 Unsubscribe` button in the sidebar. Note that you are automatically subscribed to issues you created. @@ -119,7 +119,7 @@ Tracking dependencies and duplicates 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 {#xxx}` in a comment, you can +By writing :samp:`Duplicate of #{NNN}` in a comment, you can `mark issues and PRs as duplicates `_. diff --git a/triage/labels.rst b/triage/labels.rst index ee1068aa90..8dbdcba3f8 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -44,9 +44,9 @@ These labels are mostly used to specify which :ref:`part of the codebase the :cpy-file:`Objects`, :cpy-file:`Python`, :cpy-file:`Grammar`, and :cpy-file:`Parser` dirs (written mostly in C). * :gh-label:`docs`: for documentation in the :cpy-file:`Doc` directory - (written in reStructuredText), docstrings, and code comments. + (written in :ref:`reStructuredText `), docstrings, and code comments. * :gh-label:`tests`: for tests in the :cpy-file:`Lib/test` directory - (written in Python) and changes other related to tests, ``unittest``, + (written in Python) and other changes related to tests, ``unittest``, or ``doctests``. @@ -58,7 +58,7 @@ the issue/PR. This includes both specific modules/packages and generic interest areas. Adding these labels is also a way to notify the relevant experts, since -they are encouraged to subscribe to these labels. Depending on the label, +they are encouraged to subscribe to them. Depending on the label, this might also automatically add the issue to a GitHub project. You can see the `full list of expert labels on GitHub @@ -105,7 +105,7 @@ Labels specific to PRs ====================== The following labels only apply to PRs. They are either set automatically -by bots, or applied by humans to trigger specific bot behaviors. +by bots, or added by humans to trigger specific bot behaviors. * :gh-label:`DO-NOT-MERGE`: for PRs that shouldn't be merged in their current state. It also prevents ``miss-islington`` from being able to automatically @@ -121,7 +121,7 @@ by bots, or applied by humans to trigger specific bot behaviors. * :gh-label:`skip news`: for PRs that don't need a NEWS entry. The :ref:`news-entry` section covers in details in which cases the NEWS entry can be skipped. -* :samp:`awaiting *`: these labels are applied and used by ``bedevere`` to +* :samp:`awaiting {action}`: these labels are applied and used by ``bedevere`` to indicate the stage of a PR: * :gh-label:`awaiting review`: the PR hasn't been reviewed and is waiting diff --git a/triage/triage-team.rst b/triage/triage-team.rst index cd6653e32a..68651be4a5 100644 --- a/triage/triage-team.rst +++ b/triage/triage-team.rst @@ -16,8 +16,8 @@ needed, to other repos such as devguide and core-workflow. Responsibilities include: -* Classify issues and PRs -* Applying appropriate :ref:`labels ` to PRs/Issues +* Classifying issues and PRs +* Applying appropriate :ref:`labels ` to issues/PRs * Notifying appropriate core developers * :ref:`Reviewing PRs ` * Assisting contributors From e5a4e09b57b11981e116dbaf78fe99b509761b13 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Tue, 27 Dec 2022 09:50:30 +0100 Subject: [PATCH 07/21] Apply suggestions from code review Co-authored-by: C.A.M. Gerlach Co-authored-by: Hugo van Kemenade --- triage/labels.rst | 9 ++++++--- triage/triage-team.rst | 2 +- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/triage/labels.rst b/triage/labels.rst index 8dbdcba3f8..6a7d6d2ad3 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -78,7 +78,7 @@ Version labels ============== These labels are used to indicate which versions of Python are affected. -The available version labels (with the form :samp:`3.{x}`) are updated +The available version labels (with the form :samp:`3.{N}`) are updated whenever new major releases are created or retired. See also :ref:`the branch status page ` @@ -94,6 +94,9 @@ Other labels to the build process and performances. * :gh-label:`release-blocker`/:gh-label:`deferred-blocker`: for issues/PRs that, unless fixed, will hold the current or next release respectively. + Triagers may set these labels, and the :ref:`branch's release manager ` + will review them and determine if they indeed qualify, + removing or retaining the label as appropriate. * :gh-label:`pending`: for issues/PRs that will be closed unless further feedback is provided. * :gh-label:`stale`: for issues/PRs that have been inactive for a while. @@ -108,8 +111,8 @@ The following labels only apply to PRs. They are either set automatically by bots, or added by humans to trigger specific bot behaviors. * :gh-label:`DO-NOT-MERGE`: for PRs that shouldn't be merged in their current - state. It also prevents ``miss-islington`` from being able to automatically - merge the PR. + state. It also prevents `miss-islington ` + from being able to automatically merge the PR. * :samp:`needs backport to {X.Y}`: used to indicate which branches the PR should be backported to. Once the PR is merged, ``miss-islington`` will automatically attempt to create backport PRs for the versions indicated diff --git a/triage/triage-team.rst b/triage/triage-team.rst index 68651be4a5..a48b94f7f6 100644 --- a/triage/triage-team.rst +++ b/triage/triage-team.rst @@ -42,7 +42,7 @@ following: If a triager has any doubt about whether to close a PR, they should consult a core developer before taking any action. -Triagers can also make use of the ``pending`` and ``stale`` labels to suggest that a +Triagers can also make use of the :gh-label:`pending` and :gh-label:`stale` labels to suggest that a PR may be suitable for closure. For more information, see the :ref:`GitHub PR labels ` section. From 9983fc2e75daf228f5f6e7362ad720c0982fa2b0 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Tue, 27 Dec 2022 01:58:00 -0700 Subject: [PATCH 08/21] Fix miss-islington link markup. --- triage/labels.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/triage/labels.rst b/triage/labels.rst index 6a7d6d2ad3..55cb7fa7e9 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -111,8 +111,8 @@ The following labels only apply to PRs. They are either set automatically by bots, or added by humans to trigger specific bot behaviors. * :gh-label:`DO-NOT-MERGE`: for PRs that shouldn't be merged in their current - state. It also prevents `miss-islington ` - from being able to automatically merge the PR. + state. It also prevents `miss-islington`_ from being able to automatically + merge the PR. * :samp:`needs backport to {X.Y}`: used to indicate which branches the PR should be backported to. Once the PR is merged, ``miss-islington`` will automatically attempt to create backport PRs for the versions indicated @@ -145,3 +145,4 @@ by bots, or added by humans to trigger specific bot behaviors. .. _Reporting security issues in Python: https://www.python.org/dev/security/ .. _Ideas Discourse category: https://discuss.python.org/c/ideas/6 +.. _miss-islington: https://github.com/python/miss-islington From a783cd3c600fd355f52a4ae7cc6a957bb3569f92 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Tue, 14 Mar 2023 14:34:53 +0100 Subject: [PATCH 09/21] Add more ref targets to prevent link rotting. Co-authored-by: C.A.M. Gerlach Co-authored-by: Hugo van Kemenade --- triage/labels.rst | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/triage/labels.rst b/triage/labels.rst index 55cb7fa7e9..6c7c3e5bd4 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -26,9 +26,8 @@ These labels are used to specify the type of issue: * :gh-label:`type-security`: for security issues. See also `Reporting security issues in Python`_. -Since most PRs have an associated issue, it is not necessary to apply these -labels to PRs. +.. _Component: Component labels ================ @@ -74,6 +73,8 @@ the only available labels are :gh-label:`OS-windows`, :gh-label:`OS-mac`, and :gh-label:`OS-freebsd`. +.. _Versions: + Version labels ============== @@ -85,6 +86,10 @@ See also :ref:`the branch status page ` for a list of active branches. +.. _Keywords: +.. _Other: +.. _Priority: + Other labels ============ @@ -104,6 +109,8 @@ Other labels during official sprints. +.. _GitHub Labels for PRs: + Labels specific to PRs ====================== From eed66808efc38217b557f8c030341fb2c4d5a412 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Tue, 14 Mar 2023 14:39:57 +0100 Subject: [PATCH 10/21] Add other two ref targets to the "Type labels" section. --- triage/labels.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/triage/labels.rst b/triage/labels.rst index 6c7c3e5bd4..c1398a1664 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -11,6 +11,9 @@ only to one. Below is a possibly inexhaustive list, but it should get you going. For a full list, see `here `_. +.. _general-purpose-labels: +.. _Type: + Type labels =========== From 42842c407d105ba6a4b5642a6d5770f5c4220f44 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Tue, 14 Mar 2023 22:51:05 +0800 Subject: [PATCH 11/21] Address remaining review comments. --- triage/issue-tracker.rst | 5 +++-- triage/labels.rst | 23 +++++------------------ triage/triage-team.rst | 2 +- 3 files changed, 9 insertions(+), 21 deletions(-) diff --git a/triage/issue-tracker.rst b/triage/issue-tracker.rst index a2069e2af8..da6375b535 100644 --- a/triage/issue-tracker.rst +++ b/triage/issue-tracker.rst @@ -86,10 +86,11 @@ The submission form has only two fields that you need to fill: You can tag someone, with :samp:`@{username}` in a comment, if you think the issue should be brought to their attention. -Use the :ref:`experts` to know who wants to be tagged for specific areas. +Use the :ref:`experts` to know who wants to be +tagged or assigned for specific areas. There are a number of additional fields like **Assignees**, **Labels**, -**Projects**, and **Milestone**. Those are filled by triagers and core +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. diff --git a/triage/labels.rst b/triage/labels.rst index c1398a1664..ec03876101 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -76,8 +76,6 @@ the only available labels are :gh-label:`OS-windows`, :gh-label:`OS-mac`, and :gh-label:`OS-freebsd`. -.. _Versions: - Version labels ============== @@ -134,25 +132,14 @@ by bots, or added by humans to trigger specific bot behaviors. * :gh-label:`skip news`: for PRs that don't need a NEWS entry. The :ref:`news-entry` section covers in details in which cases the NEWS entry can be skipped. -* :samp:`awaiting {action}`: these labels are applied and used by ``bedevere`` to - indicate the stage of a PR: - - * :gh-label:`awaiting review`: the PR hasn't been reviewed and is waiting - for a review. - * :gh-label:`awaiting core review`: a review by a core developer is needed. - * :gh-label:`awaiting changes`: a reviewer requested changes to proceed with - the PR. - * :gh-label:`awaiting change review`: a review of the requested changes - is needed. - * :gh-label:`awaiting merge`: the PR has been approved by a core developer - and is ready to merge. - * :gh-label:`test-with-buildbots`: used to test the latest commit with - the buildbot fleet whenever more testing is required before merging. - This may take multiple hours to complete. Triagers can also stop - a stuck build using the web interface. + the :ref:`buildbot fleet ` whenever more testing is required + before merging. This may take multiple hours to complete. +* :samp:`awaiting {action}`: these labels are applied and used by `bedevere`_ + to indicate the stage of a PR and should not be applied manually. .. _Reporting security issues in Python: https://www.python.org/dev/security/ .. _Ideas Discourse category: https://discuss.python.org/c/ideas/6 .. _miss-islington: https://github.com/python/miss-islington +.. _bedevere: https://github.com/python/bedevere/#pr-state-machine diff --git a/triage/triage-team.rst b/triage/triage-team.rst index a48b94f7f6..eac9b1a7b5 100644 --- a/triage/triage-team.rst +++ b/triage/triage-team.rst @@ -44,7 +44,7 @@ developer before taking any action. Triagers can also make use of the :gh-label:`pending` and :gh-label:`stale` labels to suggest that a PR may be suitable for closure. For more information, see the -:ref:`GitHub PR labels ` section. +:ref:`other` section. Note that it is of paramount importance to treat every contributor to the Python project kindly and with respect. Regardless of whether they're entirely new From b3590e26d29e61812269937bb066bfa30b57bb17 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Wed, 15 Mar 2023 15:43:27 +0100 Subject: [PATCH 12/21] Apply more suggestions from code review. Co-authored-by: C.A.M. Gerlach --- getting-started/setup-building.rst | 2 +- triage/issue-tracker.rst | 2 +- triage/labels.rst | 17 +++++++++++------ triage/triage-team.rst | 2 +- 4 files changed, 14 insertions(+), 9 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index f25596c784..576695c353 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -577,7 +577,7 @@ support. For editors and tools which the core developers have felt some special comment is needed for coding *in* Python, see :ref:`resources`. -.. _directory-structure: +.. _build-directory-structure: Directory structure =================== diff --git a/triage/issue-tracker.rst b/triage/issue-tracker.rst index da6375b535..889d71e9ab 100644 --- a/triage/issue-tracker.rst +++ b/triage/issue-tracker.rst @@ -110,7 +110,7 @@ Following issues 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` +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. diff --git a/triage/labels.rst b/triage/labels.rst index ec03876101..654aa3a9da 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -13,6 +13,7 @@ you going. For a full list, see `here ` is affected by the issue/PR: +` is affected by the issue/PR: * :gh-label:`stdlib`: for standard library modules in the :cpy-file:`Lib` directory (written in Python). @@ -48,8 +50,8 @@ These labels are mostly used to specify which :ref:`part of the codebase * :gh-label:`docs`: for documentation in the :cpy-file:`Doc` directory (written in :ref:`reStructuredText `), docstrings, and code comments. * :gh-label:`tests`: for tests in the :cpy-file:`Lib/test` directory - (written in Python) and other changes related to tests, ``unittest``, - or ``doctests``. + (written in Python) and other changes related to tests, :mod:`unittest`, + or :mod:`doctest`. Expert labels @@ -90,6 +92,7 @@ for a list of active branches. .. _Keywords: .. _Other: .. _Priority: +.. _labels-other: Other labels ============ @@ -100,22 +103,24 @@ Other labels to the build process and performances. * :gh-label:`release-blocker`/:gh-label:`deferred-blocker`: for issues/PRs that, unless fixed, will hold the current or next release respectively. - Triagers may set these labels, and the :ref:`branch's release manager ` + Triagers may set these labels for issues that must be fixed before a release, + and the :ref:`branch's release manager ` will review them and determine if they indeed qualify, removing or retaining the label as appropriate. * :gh-label:`pending`: for issues/PRs that will be closed unless further feedback is provided. * :gh-label:`stale`: for issues/PRs that have been inactive for a while. -* :gh-label:`sprint`: used for easier filtering of issues/PRs being worked on +* :gh-label:`sprint`: for easier filtering of issues/PRs being worked on during official sprints. .. _GitHub Labels for PRs: +.. _github-pr-labels: Labels specific to PRs ====================== -The following labels only apply to PRs. They are either set automatically +The following labels only apply to :ref:`Pull Requests `. They are either set automatically by bots, or added by humans to trigger specific bot behaviors. * :gh-label:`DO-NOT-MERGE`: for PRs that shouldn't be merged in their current diff --git a/triage/triage-team.rst b/triage/triage-team.rst index eac9b1a7b5..9abe346b42 100644 --- a/triage/triage-team.rst +++ b/triage/triage-team.rst @@ -44,7 +44,7 @@ developer before taking any action. Triagers can also make use of the :gh-label:`pending` and :gh-label:`stale` labels to suggest that a PR may be suitable for closure. For more information, see the -:ref:`other` section. +entries in the :ref:`labels-other` section. Note that it is of paramount importance to treat every contributor to the Python project kindly and with respect. Regardless of whether they're entirely new From 7c54ccf960e06afd407857a3962534afb0f0b960 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Wed, 15 Mar 2023 23:14:53 +0800 Subject: [PATCH 13/21] Rephrase sentence as suggested in a review comment. --- triage/labels.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/triage/labels.rst b/triage/labels.rst index 654aa3a9da..a6fd6bd743 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -99,8 +99,8 @@ Other labels * :gh-label:`triaged`: for issue has been accepted as valid by a triager. * :gh-label:`easy`: for issues that are considered easy. -* :gh-label:`build`/:gh-label:`performance`: for issues related respectively - to the build process and performances. +* :gh-label:`build`/:gh-label:`performance`: for issues related + to the build process or performances, respectively. * :gh-label:`release-blocker`/:gh-label:`deferred-blocker`: for issues/PRs that, unless fixed, will hold the current or next release respectively. Triagers may set these labels for issues that must be fixed before a release, From 89b29bb53e369edc1b47b1ee8a6ac28c0bdb1fe7 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Wed, 15 Mar 2023 23:15:23 +0800 Subject: [PATCH 14/21] Rewrap a few long lines. --- triage/labels.rst | 5 +++-- triage/triage-team.rst | 14 +++++++------- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/triage/labels.rst b/triage/labels.rst index a6fd6bd743..1ae9528567 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -120,8 +120,9 @@ Other labels Labels specific to PRs ====================== -The following labels only apply to :ref:`Pull Requests `. They are either set automatically -by bots, or added by humans to trigger specific bot behaviors. +The following labels only apply to :ref:`Pull Requests `. +They are either set automatically by bots, or added by humans +to trigger specific bot behaviors. * :gh-label:`DO-NOT-MERGE`: for PRs that shouldn't be merged in their current state. It also prevents `miss-islington`_ from being able to automatically diff --git a/triage/triage-team.rst b/triage/triage-team.rst index 9abe346b42..a3e703595d 100644 --- a/triage/triage-team.rst +++ b/triage/triage-team.rst @@ -39,12 +39,12 @@ following: - PRs proposing changes that have been rejected by Python core developers elsewhere (e.g. in an issue or a PEP rejection notice) -If a triager has any doubt about whether to close a PR, they should consult a core -developer before taking any action. +If a triager has any doubt about whether to close a PR, +they should consult a core developer before taking any action. -Triagers can also make use of the :gh-label:`pending` and :gh-label:`stale` labels to suggest that a -PR may be suitable for closure. For more information, see the -entries in the :ref:`labels-other` section. +Triagers can also make use of the :gh-label:`pending` and :gh-label:`stale` +labels to suggest that a PR may be suitable for closure. +For more information, see the entries in the :ref:`labels-other` section. Note that it is of paramount importance to treat every contributor to the Python project kindly and with respect. Regardless of whether they're entirely new @@ -65,8 +65,8 @@ more repositories than just CPython. When you have consistently shown the ability to properly help triage issues without guidance, you may request that you -be given the "Triager" role on the :ref:`issue tracker `. You can make the request -to any core developer. If they decide you are ready +be given the "Triager" role on the :ref:`issue tracker `. +You can make the request to any core developer. If they decide you are ready to gain the extra privileges on the tracker they will then act as a mentor to you until you are ready to do things entirely on your own. There is no set rule as to how many issues you need to have helped with before or how long you have From ee6fecd30e1d7a9758b976e60cc010c150edfa54 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Wed, 15 Mar 2023 23:23:38 +0800 Subject: [PATCH 15/21] Restore and move the `Assignees` sub-section. --- triage/triaging.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/triage/triaging.rst b/triage/triaging.rst index 0fcb7f5889..d3bb46b680 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -28,6 +28,22 @@ Checklist for Triaging .. note:: Some of these fields can only be set/edited by core developers. +Assignees +--------- +This field indicates who is expected to take the next step in resolving +the issue. + +It is acceptable to assign an issue to someone if the issue cannot move +forward without their help, e.g., they need to make a technical decision to +allow the issue to move forward. Also consult the :ref:`experts` as certain +stdlib modules should always be assigned to a specific person. + +Note that in order to assign an issue to someone, that person **must** be +a team member, likely a Triager or a core developer. + +.. The Assignees subsection was copied from the labels.rst page in #930. + For consistency, other the fields mentioned above should be documented too. + .. _helptriage: From 8d8a52ba4fb788b6082f10001402d4adc440241f Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Thu, 16 Mar 2023 10:52:57 +0100 Subject: [PATCH 16/21] Fix typo. Co-authored-by: Hugo van Kemenade --- triage/triaging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/triage/triaging.rst b/triage/triaging.rst index d3bb46b680..40397ac825 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -42,7 +42,7 @@ Note that in order to assign an issue to someone, that person **must** be a team member, likely a Triager or a core developer. .. The Assignees subsection was copied from the labels.rst page in #930. - For consistency, other the fields mentioned above should be documented too. + For consistency, the other fields mentioned above should be documented too. .. _helptriage: From 52eea4d7476f3c2729a337e7acba5183a3fbe85e Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Thu, 16 Mar 2023 15:54:14 +0100 Subject: [PATCH 17/21] Fix "triager" capitalization. Co-authored-by: Hugo van Kemenade --- triage/triaging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/triage/triaging.rst b/triage/triaging.rst index 40397ac825..120a936386 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -39,7 +39,7 @@ allow the issue to move forward. Also consult the :ref:`experts` as certain stdlib modules should always be assigned to a specific person. Note that in order to assign an issue to someone, that person **must** be -a team member, likely a Triager or a core developer. +a team member, likely a triager or a core developer. .. The Assignees subsection was copied from the labels.rst page in #930. For consistency, the other fields mentioned above should be documented too. From 5f1f47880ee9de66d39b8d890b0b8bba8473c374 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Thu, 16 Mar 2023 23:02:53 +0800 Subject: [PATCH 18/21] Document the `automerge` label. --- triage/labels.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/triage/labels.rst b/triage/labels.rst index 1ae9528567..a2271e40ea 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -124,6 +124,8 @@ The following labels only apply to :ref:`Pull Requests `. They are either set automatically by bots, or added by humans to trigger specific bot behaviors. +* :gh-label:`automerge`: used to automatically merge PRs approved + by a core dev once all tests are passing. * :gh-label:`DO-NOT-MERGE`: for PRs that shouldn't be merged in their current state. It also prevents `miss-islington`_ from being able to automatically merge the PR. From 4db1138a591a0a53b672eb0f1d6ee65916fc5d89 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Thu, 16 Mar 2023 23:05:14 +0800 Subject: [PATCH 19/21] Remove obsolete note/comment. --- triage/triaging.rst | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/triage/triaging.rst b/triage/triaging.rst index 120a936386..aedfea0fb9 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -24,12 +24,9 @@ Checklist for Triaging * 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. - Assignees --------- + This field indicates who is expected to take the next step in resolving the issue. From ff2d0ee9a763822e43c3afaead21f00d372cbf0b Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Thu, 16 Mar 2023 16:11:05 +0100 Subject: [PATCH 20/21] Minor grammar/punctuation/phrasing fixes. Co-authored-by: C.A.M. Gerlach --- triage/labels.rst | 2 +- triage/triaging.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/triage/labels.rst b/triage/labels.rst index a2271e40ea..0460f52b4e 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -100,7 +100,7 @@ Other labels * :gh-label:`triaged`: for issue has been accepted as valid by a triager. * :gh-label:`easy`: for issues that are considered easy. * :gh-label:`build`/:gh-label:`performance`: for issues related - to the build process or performances, respectively. + to the build process or performance, respectively. * :gh-label:`release-blocker`/:gh-label:`deferred-blocker`: for issues/PRs that, unless fixed, will hold the current or next release respectively. Triagers may set these labels for issues that must be fixed before a release, diff --git a/triage/triaging.rst b/triage/triaging.rst index aedfea0fb9..9e0a621553 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -31,8 +31,8 @@ This field indicates who is expected to take the next step in resolving the issue. It is acceptable to assign an issue to someone if the issue cannot move -forward without their help, e.g., they need to make a technical decision to -allow the issue to move forward. Also consult the :ref:`experts` as certain +forward without their help; e.g., they need to make a technical decision on +how to proceed. Also consult the :ref:`experts` as certain stdlib modules should always be assigned to a specific person. Note that in order to assign an issue to someone, that person **must** be From 9b9482f2a26e4d3d81b605d617bc88f419f6bf81 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Thu, 16 Mar 2023 16:20:28 +0100 Subject: [PATCH 21/21] Final tweaks. Co-authored-by: C.A.M. Gerlach --- triage/labels.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/triage/labels.rst b/triage/labels.rst index 0460f52b4e..59fe2880bd 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -124,8 +124,8 @@ The following labels only apply to :ref:`Pull Requests `. They are either set automatically by bots, or added by humans to trigger specific bot behaviors. -* :gh-label:`automerge`: used to automatically merge PRs approved - by a core dev once all tests are passing. +* :gh-label:`automerge`: for automatically merging PRs approved + by a core dev once all CI checks pass. * :gh-label:`DO-NOT-MERGE`: for PRs that shouldn't be merged in their current state. It also prevents `miss-islington`_ from being able to automatically merge the PR.