From ff65cdd440fdb00e9c78808269dc0a5b344525ca Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Wed, 16 Dec 2020 02:01:33 -0500 Subject: [PATCH] GOV/DOC: add section to docs on triaging and triage team Co-authored-by: Elliott Sales de Andrade Co-authored-by: hannah --- doc/devel/index.rst | 1 + doc/devel/triage.rst | 227 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 228 insertions(+) create mode 100644 doc/devel/triage.rst diff --git a/doc/devel/index.rst b/doc/devel/index.rst index ea83129824c1..a172c6e53c67 100644 --- a/doc/devel/index.rst +++ b/doc/devel/index.rst @@ -17,6 +17,7 @@ The Matplotlib Developers' Guide :maxdepth: 2 contributing.rst + triage.rst testing.rst documenting_mpl.rst add_new_projection.rst diff --git a/doc/devel/triage.rst b/doc/devel/triage.rst new file mode 100644 index 000000000000..b57947b049b7 --- /dev/null +++ b/doc/devel/triage.rst @@ -0,0 +1,227 @@ + +.. _bug_triaging: + +Bug triaging and issue curation +=============================== + +The `issue tracker `_ +is important to communication in the project because it serves as the +centralized location for making feature requests, reporting bugs, +identifying major projects to work on, and discussing priorities. For +this reason, it is important to curate the issue list, adding labels +to issues and closing issues that are resolved or unresolvable. + +Triaging issues does not require any particular expertise in the +internals of Matplotlib, is extremely valuable to the project, and we +welcome anyone to participate in issue triage! However, people who +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 tagging +``@matplotlib/triageteam`` with your recommendations! + +Working on issues to improve them +--------------------------------- + +Improving issues increases their chances of being successfully resolved. +Guidelines on submitting good issues can be found :ref:`here +`. +A third party can give useful feedback or even add +comments on the issue. +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 + 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 + +.. 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 + different understanding of the process than a seasoned maintainer. + + Overall, it is useful to stay positive and assume good will. `The + following article + `_ + explores how to lead online discussions in the context of open source. + + +Triage Team +----------- + + +If you would like to join the triage team: + +1. Correctly triage 2-3 issues. +2. Ask someone on the `triage team + `_ (publicly + or privately) to recommend you to the triage team . If you worked + with someone on the issue triaged, they would be a good person to + ask. +3. Responsibly exercise your new power! + +Anyone with commit or triage rights may also nominate a user to be +invited to join the triage team. + + + +Triaging operations for members of the core and triage teams +------------------------------------------------------------ + +In addition to the above, members of the core team and the triage team +can do the following important tasks: + +- Update labels for issues and PRs: see the list of `available github + labels `_. + +- 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 + 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 + 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 + + + +.. topic:: Closing issues: a tough call + + When uncertain on whether an issue should be closed or not, it is + best to strive for consensus with the original poster, and possibly + to seek relevant expertise. However, when the issue is a usage + question or has been considered as unclear for many years, then it + should be closed. + + +A typical workflow for triaging issues +-------------------------------------- + +The following workflow [1]_ is a good way to approach issue triaging: + +#. Thank the reporter for opening an issue + + The issue tracker is many people’s first interaction with the + 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 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 + poster to provide the information. + +#. Is the issue minimal and reproducible? + + For bug reports, we ask that the reporter provide a minimal + reproducible example. See `this useful post + `_ + by Matthew Rocklin for a good explanation. If the example is not + reproducible, or if it's clearly not minimal, feel free to ask the reporter + if they can provide an example or simplify the provided one. + Do acknowledge that writing minimal reproducible examples is hard work. + If the reporter is struggling, you can try to write one yourself. + + If a reproducible example is provided, but you see a simplification, + add your simpler reproducible example. + + If you can not reproduce the issue, please report that along with your + 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". + +#. Is this a regression? + + While we strive for a bug-free library, regressions are the highest + priority. If we have broken user-code that *used to* work, we should + fix that in the next patch release! + + Try to determine when the regression happened by running the + reproduction code against older versions of Matplotlib. This can + be done by released versions of Matplotlib (to get the version it + last worked in) or by using `git bisect + `_ 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, + point to the original issue. If it is a clear duplicate, or consensus + is that it is redundant, close it. Make sure to still thank the + reporter, and encourage them to chime in on the original issue, and + perhaps try to fix it. + + If the new issue provides relevant information, such as a better or + 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" + +#. 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). + + An additional useful step can be to tag the corresponding module e.g. + the "GUI/Qt" label when relevant. + + +.. [1] Adapted from the pandas project `maintainers guide + `_ and + `the scikit-learn project + `_ . + + +Working on PRs to help review +------------------------------ + +Reviewing code is also encouraged. Contributors and users are welcome to +participate to the review process following our :ref:`review guidelines +`. + +Acknowledgments +--------------- + +This page is lightly adapted from `the sckit-learn project +`_ . pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy