matplotlib · tacaswell · Dec 23, 2020 · Dec 16, 2020
diff --git 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
@@ -0,0 +1,227 @@
+
+.. _bug_triaging:
+
+Bug triaging and issue curation
+===============================
+
+The `issue tracker <https://github.com/matplotlib/matplotlib/issues>`_
+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
+<https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization>`_.
+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
+<submitting-a-bug-report>`.
+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
+   <http://gael-varoquaux.info/programming/technical-discussions-are-hard-a-few-tips.html>`_
+   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
+   <https://github.com/orgs/matplotlib/teams/triageteam>`_ (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 <https://github.com/matplotlib/matplotlib/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 <https://discourse.matplotlib.org>`_ 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
+   <https://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports>`_
+   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
+   <https://git-scm.com/docs/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
+       <https://dev.pandas.io/docs/development/maintaining.html>`_ and
+       `the scikit-learn project
+       <https://scikit-learn.org/dev/developers/bug_triaging.html>`_ .
+
+
+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
+<pr-guidelines>`.
+
+Acknowledgments
+---------------
+
+This page is lightly adapted from `the sckit-learn project
+<https://scikit-learn.org/dev/developers/bug_triaging.html>`_ .