Bug triage 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.

Writing well defined issues increases their chances of being successfully resolved. Guidelines on writing a good issue can be found in here. The recommendations in this page are adapted from the scikit learn and Pandas contributing guides.

Improve issue reports

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 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 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", 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.

Fruitful discussions

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 following article explores how to lead online discussions in the context of open source.

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 labels.

• Triage issues:

  • 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 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.

  • 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.

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.

Triage workflow

The following workflow is a good way to approach issue triaging:

1. 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.

2. 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.

3. 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.

4. 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 cannot 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.

5. 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 micro 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.

6. 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.

7. Make sure that the title accurately reflects the issue. If you have the necessary permissions edit it yourself if it's not clear.

8. 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 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.

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 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 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 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

If you would like to join the triage team:

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 would be a good person to ask.

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 nominating them through the private "Triage team nominations" category on Discourse (Note that only @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.

If no objections are raised within one week of the nomination, a member with the owner role on GitHub will: 1. Send an invitation email to the nominee following a template. 2. Once the nominee responds affirmatively, they will add the nominee to the Triage group on GitHub, and to the @triage group on Discourse. 3. Close the Discourse thread with a confirmation that the nomination was accepted (or turned down).

If objections are raised, no action will be taken and the nomination can be revisited in the future.