From cd77acda17c8631bd189f495f9ba2a108dab2363 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= Date: Thu, 5 Feb 2026 15:44:56 -0300 Subject: [PATCH 1/6] DOC: Update triage team nomination instructions --- doc/devel/triage.rst | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/doc/devel/triage.rst b/doc/devel/triage.rst index ca06fd515c79..2ddbce0bf52c 100644 --- a/doc/devel/triage.rst +++ b/doc/devel/triage.rst @@ -204,10 +204,13 @@ The following workflow is a good way to approach issue triaging: Triage team =========== - If you would like to join the triage team: -1. Correctly triage 2-3 issues. +1. Correctly triage 2-3 issues or review 2-3 pull requests. Actually labeling or + closing issues and PRs require triage permissions, but you can verify with + comments if issues have enough information or are still valid, and suggest + changes to PRs, particularly if you can help contributors solve CI check + failures. 2. Ask someone on in the Matplotlib organization (publicly or privately) to recommend you to the triage team (look for "Member" on the top-right of comments on GitHub). If you worked with someone on the issues triaged, they @@ -215,4 +218,6 @@ If you would like to join the triage team: 3. Responsibly exercise your new power! Anyone with commit or triage rights may nominate a user to be invited to join -the triage team by emailing matplotlib-steering-council@numfocus.org . +the triage team by nominating them through the private "Triage team nominations" +category on `Discourse `__ (Note that only +``Staff`` members can see this category). From 8528a0dbc558772c5f2122a0143171daeae3d3d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= Date: Wed, 4 Mar 2026 17:23:09 -0300 Subject: [PATCH 2/6] DOC: More updates to triage triage doc --- doc/devel/triage.rst | 148 ++++++++++++++++++++++++------------------- 1 file changed, 84 insertions(+), 64 deletions(-) diff --git a/doc/devel/triage.rst b/doc/devel/triage.rst index 2ddbce0bf52c..f2047eb120fa 100644 --- a/doc/devel/triage.rst +++ b/doc/devel/triage.rst @@ -30,35 +30,29 @@ are not part of the Matplotlib organization do not have `permissions to change milestones, add labels, or close issue `_. -If you do not have enough GitHub permissions do something (e.g. add a -label, close an issue), please leave a comment with your -recommendations! +If you do not have enough GitHub permissions to do something (e.g. add a +label, close an issue), please leave a comment with your recommendations! The following actions are typically useful: -- documenting issues that are missing elements to reproduce the problem - such as code samples - -- suggesting better use of code formatting (e.g. triple back ticks in the - markdown). - -- suggesting to reformulate the title and description to make them more - explicit about the problem to be solved - -- linking to related issues or discussions while briefly describing +* documenting issues that are missing elements to reproduce the problem, + such as code samples; +* suggesting better use of code formatting (e.g. triple back ticks in the + markdown); +* suggesting to reformulate the title and description to make them more + explicit about the problem to be solved; +* linking to related issues or discussions while briefly describing how they are related, for instance "See also #xyz for a similar attempt at this" or "See also #xyz where the same thing was - reported" provides context and helps the discussion - -- verifying that the issue is reproducible - -- classify the issue as a feature request, a long standing bug or a - regression + reported", which provides context and helps the discussion; +* verifying that the issue is reproducible; +* classifying the issue as a feature request, a long standing bug or a + regression. .. topic:: Fruitful discussions - Online discussions may be harder than it seems at first glance, in - particular given that a person new to open-source may have a very + Online discussions may be harder than they seem at first glance, in + particular given that a person new to open source may have a very different understanding of the process than a seasoned maintainer. Overall, it is useful to stay positive and assume good will. `The @@ -73,31 +67,26 @@ Maintainers and triage team members In addition to the above, maintainers and the triage team can do the following important tasks: -- Update labels for issues and PRs: see the list of `available GitHub +* Update labels for issues and PRs: see the list of `available GitHub labels `_. +* Triage issues: -- Triage issues: - - - **reproduce the issue**, if the posted code is a bug label the issue - with "status: confirmed bug". - - - **identify regressions**, determine if the reported bug used to + * **reproduce the issue**, and if the posted code is a bug label the issue + with `status: confirmed bug `_. + * **identify regressions**, determine if the reported bug used to work as expected in a recent version of Matplotlib and if so determine the last working version. Regressions should be milestoned for the next bug-fix release and may be labeled as "Release critical". - - - **close usage questions** and politely point the reporter to use - `discourse `_ or Stack Overflow - instead and label as "community support". - - - **close duplicate issues**, after checking that they are + * **close duplicate issues**, after checking that they are indeed duplicate. Ideally, the original submitter moves the - discussion to the older, duplicate issue - - - **close issues that cannot be replicated**, after leaving time (at - least a week) to add extra information - + discussion to the older, duplicate issue. + * **close issues that cannot be replicated**, after leaving time (at + least a week) to add extra information. + * **invite contributors to engage with the community** if the issue requires + more information or discussion. These discussions can take place in the + `weekly community meetings `__, or + on `discourse `_. .. topic:: Closing issues: a tough call @@ -107,13 +96,6 @@ important tasks: question or has been considered as unclear for many years, then it should be closed. -Preparing PRs for review -======================== - -Reviewing code is also encouraged. Contributors and users are welcome to -participate to the review process following our :ref:`review guidelines -`. - .. _triage_workflow: Triage workflow @@ -127,13 +109,18 @@ The following workflow is a good way to approach issue triaging: Matplotlib project itself, beyond just using the library. As such, we want it to be a welcoming, pleasant experience. -#. Is this a usage question? If so close it with a polite message. +#. Is this a usage question? + + If so, close it with a polite message, point the reporter to use + `discourse `_ or Stack Overflow instead and + use the `community support `_ + label, if you have the necessary permissions. #. Is the necessary information provided? Check that the poster has filled in the issue template. If crucial information (the version of Python, the version of Matplotlib used, - the OS, and the backend), is missing politely ask the original + the OS, and the backend) is missing, politely ask the original poster to provide the information. #. Is the issue minimal and reproducible? @@ -154,7 +141,7 @@ The following workflow is a good way to approach issue triaging: OS, Python, and Matplotlib versions. If we need more information from either this or the previous step - please label the issue with "status: needs clarification". + please label the issue with `status: needs clarification `_. #. Is this a regression? @@ -169,7 +156,6 @@ The following workflow is a good way to approach issue triaging: `_ to find the first commit where it was broken. - #. Is this a duplicate issue? We have many open issues. If a new issue seems to be a duplicate, @@ -182,23 +168,61 @@ The following workflow is a good way to approach issue triaging: slightly different example, add it to the original issue as a comment or an edit to the original post. - Label the closed issue with "status: duplicate" + Label the closed issue with `status: duplicate `_. #. Make sure that the title accurately reflects the issue. If you have the necessary permissions edit it yourself if it's not clear. -#. Add the relevant labels, such as "Documentation" when the issue is - about documentation, "Bug" if it is clearly a bug, "New feature" if it - is a new feature request, ... - - If the issue is clearly defined and the fix seems relatively - straightforward, label the issue as “Good first issue” (and - possibly a description of the fix or a hint as to where in the - code base to look to get started). +#. Add the relevant labels, such as `Documentation `_ + when the issue is about documentation, `status: confirmed bug `_ + if it is clearly a bug, `New feature `_ + if it is a new feature request, etc. An additional useful step can be to tag the corresponding module e.g. the "GUI/Qt" label when relevant. + Take some time to familiarize yourself with the available labels and their + meaning, and try to use them consistently. + +.. topic:: Good first issues + + If the issue is clearly defined, the fix seems relatively straightforward, + and there is consensus on what the solution is among maintainers, label the + issue as + `Good first issue `_ + (and possibly a description of the fix or a hint as to where in the + code base to look to get started). + + Note that good first issues are intended to onboard newcomers with a genuine + interest in improving Matplotlib, in the hopes that they will continue to + participate in our development community; therefore, the use of AI tools to + resolve these issues is not appropriate. + +Preparing PRs for review +======================== + +Doing initial reviews of contributions is also encouraged. Contributors and +users are welcome to participate to the review process following our +:ref:`review guidelines `. In particular, if you identify a PR +that needs maintainer attention, you can add the +`status: needs review `_ +label to it, or add it to the next community meeting agenda for discussion. You +can: + +* Suggest fixes to CI check failures, such as failing tests or documentation + builds; +* Help with :ref:`rebasing instructions `; +* Suggest improvements to the PR description, including filling out the AI + Disclosure section if it is missing. + +AI-generated contributions +-------------------------- + +Make sure PRs comply with our :ref:`policy on AI-generated contributions `. +If you identify a PR that does not comply with the policy, ask the contributor +to clarify the AI tools used and the contribution of the author, and to update +the PR description accordingly. + .. _triage_team: Triage team @@ -206,11 +230,7 @@ Triage team If you would like to join the triage team: -1. Correctly triage 2-3 issues or review 2-3 pull requests. Actually labeling or - closing issues and PRs require triage permissions, but you can verify with - comments if issues have enough information or are still valid, and suggest - changes to PRs, particularly if you can help contributors solve CI check - failures. +1. Correctly triage 2-3 issues or review 2-3 pull requests, as described above. 2. Ask someone on in the Matplotlib organization (publicly or privately) to recommend you to the triage team (look for "Member" on the top-right of comments on GitHub). If you worked with someone on the issues triaged, they From 6775b2d469feb62d77e5bade1109ad5bc90f8ebf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= Date: Thu, 9 Apr 2026 16:01:30 -0300 Subject: [PATCH 3/6] DOC: Try to fix linting issue in triage.rst --- doc/devel/triage.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/doc/devel/triage.rst b/doc/devel/triage.rst index f2047eb120fa..0fefc4379824 100644 --- a/doc/devel/triage.rst +++ b/doc/devel/triage.rst @@ -86,7 +86,7 @@ important tasks: * **invite contributors to engage with the community** if the issue requires more information or discussion. These discussions can take place in the `weekly community meetings `__, or - on `discourse `_. + on `discourse `__. .. topic:: Closing issues: a tough call @@ -112,8 +112,9 @@ The following workflow is a good way to approach issue triaging: #. Is this a usage question? If so, close it with a polite message, point the reporter to use - `discourse `_ or Stack Overflow instead and - use the `community support `_ + `discourse `__ or Stack Overflow instead + and use the + `community support `__ label, if you have the necessary permissions. #. Is the necessary information provided? @@ -168,14 +169,14 @@ The following workflow is a good way to approach issue triaging: slightly different example, add it to the original issue as a comment or an edit to the original post. - Label the closed issue with `status: duplicate `_. + Label the closed issue with `status: duplicate `__. #. Make sure that the title accurately reflects the issue. If you have the necessary permissions edit it yourself if it's not clear. -#. Add the relevant labels, such as `Documentation `_ - when the issue is about documentation, `status: confirmed bug `_ - if it is clearly a bug, `New feature `_ +#. Add the relevant labels, such as `Documentation `__ + when the issue is about documentation, `status: confirmed bug `__ + if it is clearly a bug, `New feature `__ if it is a new feature request, etc. An additional useful step can be to tag the corresponding module e.g. From 5c95777c307d87834b9759481c0fa8460351b0e4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= Date: Fri, 10 Apr 2026 16:44:13 -0300 Subject: [PATCH 4/6] Address review comments --- doc/devel/triage.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/devel/triage.rst b/doc/devel/triage.rst index 0fefc4379824..37c76bff35a6 100644 --- a/doc/devel/triage.rst +++ b/doc/devel/triage.rst @@ -179,8 +179,8 @@ The following workflow is a good way to approach issue triaging: if it is clearly a bug, `New feature `__ if it is a new feature request, etc. - An additional useful step can be to tag the corresponding module e.g. - the "GUI/Qt" label when relevant. + An additional useful step can be to tag with the relevant "topic: ..." label, + e.g. "topic: widgets/UI" or "topic: animation". Take some time to familiarize yourself with the available labels and their meaning, and try to use them consistently. @@ -219,10 +219,10 @@ can: AI-generated contributions -------------------------- -Make sure PRs comply with our :ref:`policy on AI-generated contributions `. -If you identify a PR that does not comply with the policy, ask the contributor -to clarify the AI tools used and the contribution of the author, and to update -the PR description accordingly. +Make sure PRs comply with our :ref:`AI policy `. If you identify +a PR that does not comply with the policy, ask the contributor to clarify the AI +tools used and the contribution of the author, and to update the PR description +accordingly to comply with our AI policy. .. _triage_team: From 5c51c98b8623265266a454a3edb775f8f90d9206 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= Date: Thu, 16 Apr 2026 14:39:25 -0300 Subject: [PATCH 5/6] Update nomination instructions and categories --- doc/devel/triage.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/devel/triage.rst b/doc/devel/triage.rst index 37c76bff35a6..cbc149072e1e 100644 --- a/doc/devel/triage.rst +++ b/doc/devel/triage.rst @@ -241,4 +241,6 @@ If you would like to join the triage team: Anyone with commit or triage rights may nominate a user to be invited to join the triage team by nominating them through the private "Triage team nominations" category on `Discourse `__ (Note that only -``Staff`` members can see this category). +``maintainers`` and ``triage`` members can see this category). The nomination +will then be confirmed by the Steering Council and the user, if accepted, will +be added to the triage team on GitHub. From d09edf5d6635515cc025dcf4ffe8006ee1c6a930 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= Date: Thu, 23 Apr 2026 15:24:53 -0300 Subject: [PATCH 6/6] Add @ to staff groups --- doc/devel/triage.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/devel/triage.rst b/doc/devel/triage.rst index cbc149072e1e..2d9f1e48f1b4 100644 --- a/doc/devel/triage.rst +++ b/doc/devel/triage.rst @@ -241,6 +241,6 @@ If you would like to join the triage team: Anyone with commit or triage rights may nominate a user to be invited to join the triage team by nominating them through the private "Triage team nominations" category on `Discourse `__ (Note that only -``maintainers`` and ``triage`` members can see this category). The nomination +``@maintainers`` and ``@triage`` members can see this category). The nomination will then be confirmed by the Steering Council and the user, if accepted, will be added to the triage team on GitHub.