Bug triaging and issue curation#

Theissue trackeris important to communication in the project because it serves as thecentralized location for making feature requests, reporting bugs,identifying major projects to work on, and discussing priorities. Forthis reason, it is important to curate the issue list, adding labelsto issues and closing issues that are resolved or unresolvable.

Writing well defined issues increases their chances of being successfullyresolved. Guidelines on writing a good issue can be found inhere. The recommendations in this page are adapted fromthescikit learnandPandascontributing guides.

Improve issue reports#

Triaging issues does not require any particular expertise in theinternals of Matplotlib, is extremely valuable to the project, and wewelcome anyone to participate in issue triage! However, people whoare not part of the Matplotlib organization do not havepermissionsto change milestones, add labels, or close issue.

If you do not have enough GitHub permissions do something (e.g. add alabel, close an issue), please leave a comment with yourrecommendations!

The following actions are typically useful:

  • documenting issues that are missing elements to reproduce the problemsuch as code samples

  • suggesting better use of code formatting (e.g. triple back ticks in themarkdown).

  • suggesting to reformulate the title and description to make them moreexplicit about the problem to be solved

  • linking to related issues or discussions while briefly describinghow they are related, for instance "See also #xyz for a similarattempt at this" or "See also #xyz where the same thing wasreported" provides context and helps the discussion

  • verifying that the issue is reproducible

  • classify the issue as a feature request, a long standing bug or aregression

Fruitful discussions

Online discussions may be harder than it seems at first glance, inparticular given that a person new to open-source may have a verydifferent understanding of the process than a seasoned maintainer.

Overall, it is useful to stay positive and assume good will.Thefollowing articleexplores 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 followingimportant tasks:

  • Update labels for issues and PRs: see the list ofavailable GitHublabels.

  • Triage issues:

    • reproduce the issue, if the posted code is a bug label the issuewith "status: confirmed bug".

    • identify regressions, determine if the reported bug used towork as expected in a recent version of Matplotlib and if sodetermine the last working version. Regressions should bemilestoned for the next bug-fix release and may be labeled as"Release critical".

    • close usage questions and politely point the reporter to usediscourse or Stack Overflowinstead and label as "community support".

    • close duplicate issues, after checking that they areindeed duplicate. Ideally, the original submitter moves thediscussion to the older, duplicate issue

    • close issues that cannot be replicated, after leaving time (atleast a week) to add extra information

Closing issues: a tough call

When uncertain on whether an issue should be closed or not, it isbest to strive for consensus with the original poster, and possiblyto seek relevant expertise. However, when the issue is a usagequestion or has been considered as unclear for many years, then itshould be closed.

Preparing PRs for review#

Reviewing code is also encouraged. Contributors and users are welcome toparticipate to the review process following ourreview guidelines.

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

  3. Is the necessary information provided?

    Check that the poster has filled in the issue template. If crucialinformation (the version of Python, the version of Matplotlib used,the OS, and the backend), is missing politely ask the originalposter to provide the information.

  4. Is the issue minimal and reproducible?

    For bug reports, we ask that the reporter provide a minimalreproducible example. Seethis useful postby Matthew Rocklin for a good explanation. If the example is notreproducible, or if it's clearly not minimal, feel free to ask the reporterif 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 yourOS, Python, and Matplotlib versions.

    If we need more information from either this or the previous stepplease label the issue with "status: needs clarification".

  5. Is this a regression?

    While we strive for a bug-free library, regressions are the highestpriority. If we have broken user-code thatused to work, we shouldfix that in the next micro release!

    Try to determine when the regression happened by running thereproduction code against older versions of Matplotlib. This canbe done by released versions of Matplotlib (to get the version itlast worked in) or by usinggit bisect to find the first commitwhere 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 consensusis that it is redundant, close it. Make sure to still thank thereporter, and encourage them to chime in on the original issue, andperhaps try to fix it.

    If the new issue provides relevant information, such as a better orslightly different example, add it to the original issue as a commentor 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 thenecessary permissions edit it yourself if it's not clear.

  8. Add the relevant labels, such as "Documentation" when the issue isabout documentation, "Bug" if it is clearly a bug, "New feature" if itis a new feature request, ...

    If the issue is clearly defined and the fix seems relativelystraightforward, label the issue as “Good first issue” (andpossibly a description of the fix or a hint as to where in thecode 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.

Triage team#

If you would like to join the triage team:

  1. Correctly triage 2-3 issues.

  2. Ask someone on in the Matplotlib organization (publicly or privately) torecommend you to the triage team (look for "Member" on the top-right ofcomments on GitHub). If you worked with someone on the issues triaged, theywould 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 jointhe triage team by emailingmatplotlib-steering-council@numfocus.org .