-
Notifications
You must be signed in to change notification settings - Fork 62
Expand file tree
/
Copy pathtriage.html
More file actions
333 lines (311 loc) · 18.2 KB
/
Copy pathtriage.html
File metadata and controls
333 lines (311 loc) · 18.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Bug triaging and issue curation — Matplotlib 3.4.2 documentation</title>
<link rel="stylesheet" href="../_static/mpl.css?v3.4.2-2-gf801f04d09-dirty" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" type="text/css" href="../_static/graphviz.css" />
<link rel="stylesheet" type="text/css" href="../_static/plot_directive.css" />
<link rel="stylesheet" type="text/css" href="../_static/copybutton.css" />
<link rel="stylesheet" type="text/css" href="../_static/gallery.css" />
<link rel="stylesheet" type="text/css" href="../_static/gallery-binder.css" />
<link rel="stylesheet" type="text/css" href="../_static/gallery-dataframe.css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script src="../_static/clipboard.min.js"></script>
<script src="../_static/copybutton.js"></script>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Matplotlib 3.4.2 documentation"
href="../_static/opensearch.xml"/>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Setting up Matplotlib for development" href="development_setup.html" />
<link rel="prev" title="Contributing" href="contributing.html" />
<link rel="top" title="Matplotlib 3.4.2 documentation" href="#" />
<link rel="canonical" href="https://matplotlib.org/stable/devel/triage.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
<script data-domain="matplotlib.org" defer="defer" src="https://views.scientific-python.org/js/script.js"></script>
</head><body>
<div id="unreleased-message"> You are reading an old version of the documentation (v3.4.2). For the latest version see <a href="https://matplotlib.org/stable/devel/triage.html">https://matplotlib.org/stable/devel/triage.html</a></div>
<!--
<div id="annc-banner">
</div>
-->
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px; position: relative;">
<a href="../index.html">
<div style="float: left; position: absolute; width: 496px; bottom: 0; padding-bottom: 24px"><span style="float: right; color: #789; background: white">Version 3.4.2</span></div>
<img src="../_static/logo2_compressed.svg" height="125px" border="0" alt="matplotlib"/></a>
<!-- The "Fork me on github" ribbon -->
<div id="forkongithub"><a href="https://github.com/matplotlib/matplotlib">Fork me on GitHub</a></div>
</div>
<nav class="main-nav">
<ul>
<li><a href="../users/installing.html">Installation</a></li>
<li><a href="../contents.html">Documentation</a></li>
<li><a href="../gallery/index.html">Examples</a></li>
<li><a href="../tutorials/index.html">Tutorials</a></li>
<li><a href="index.html">Contributing</a></li>
<li class="nav-right">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" placeholder="Search"/>
</form>
</li>
</ul>
</nav>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="development_setup.html" title="Setting up Matplotlib for development"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="contributing.html" title="Contributing"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">home</a>| </li>
<li><a href="../contents.html">contents</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">The Matplotlib Developers' Guide</a> »</li>
<li class="nav-item nav-item-this"><a href="">Bug triaging and issue curation</a></li>
</ul>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Bug triaging and issue curation</a><ul>
<li><a class="reference internal" href="#working-on-issues-to-improve-them">Working on issues to improve them</a></li>
<li><a class="reference internal" href="#triage-team">Triage Team</a></li>
<li><a class="reference internal" href="#triaging-operations-for-members-of-the-core-and-triage-teams">Triaging operations for members of the core and triage teams</a></li>
<li><a class="reference internal" href="#a-typical-workflow-for-triaging-issues">A typical workflow for triaging issues</a></li>
<li><a class="reference internal" href="#working-on-prs-to-help-review">Working on PRs to help review</a></li>
<li><a class="reference internal" href="#acknowledgments">Acknowledgments</a></li>
</ul>
</li>
</ul>
<div id="sidebar-pagesource" role="note" aria-label="source link"
style="margin-top: 1.5em; padding-top: 0.1em; border-top: 1px solid #86989b">
<a href="../_sources/devel/triage.rst.txt"
style="color: #c0c0c0" rel="nofollow">Show Page Source</a>
</div>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="bug-triaging-and-issue-curation">
<span id="bug-triaging"></span><h1>Bug triaging and issue curation<a class="headerlink" href="#bug-triaging-and-issue-curation" title="Permalink to this headline">¶</a></h1>
<p>The <a class="reference external" href="https://github.com/matplotlib/matplotlib/issues">issue tracker</a>
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.</p>
<p>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 <a class="reference external" href="https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization">permissions
to change milestones, add labels, or close issue</a>.
If you do not have enough GitHub permissions do something (e.g. add a
label, close an issue), please leave a comment tagging
<code class="docutils literal notranslate"><span class="pre">@matplotlib/triageteam</span></code> with your recommendations!</p>
<div class="section" id="working-on-issues-to-improve-them">
<h2>Working on issues to improve them<a class="headerlink" href="#working-on-issues-to-improve-them" title="Permalink to this headline">¶</a></h2>
<p>Improving issues increases their chances of being successfully resolved.
Guidelines on submitting good issues can be found <a class="reference internal" href="contributing.html#submitting-a-bug-report"><span class="std std-ref">here</span></a>.
A third party can give useful feedback or even add
comments on the issue.
The following actions are typically useful:</p>
<blockquote>
<div><ul class="simple">
<li>documenting issues that are missing elements to reproduce the problem
such as code samples</li>
<li>suggesting better use of code formatting (e.g. triple back ticks in the
markdown).</li>
<li>suggesting to reformulate the title and description to make them more
explicit about the problem to be solved</li>
<li>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</li>
<li>verifying that the issue is reproducible</li>
<li>classify the issue as a feature request, a long standing bug or a
regression</li>
</ul>
</div></blockquote>
<div class="topic">
<p class="topic-title">Fruitful discussions</p>
<p>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.</p>
<p>Overall, it is useful to stay positive and assume good will. <a class="reference external" href="http://gael-varoquaux.info/programming/technical-discussions-are-hard-a-few-tips.html">The
following article</a>
explores how to lead online discussions in the context of open source.</p>
</div>
</div>
<div class="section" id="triage-team">
<h2>Triage Team<a class="headerlink" href="#triage-team" title="Permalink to this headline">¶</a></h2>
<p>If you would like to join the triage team:</p>
<ol class="arabic simple">
<li>Correctly triage 2-3 issues.</li>
<li>Ask someone on the <a class="reference external" href="https://github.com/orgs/matplotlib/teams/triageteam">triage team</a> (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.</li>
<li>Responsibly exercise your new power!</li>
</ol>
<p>Anyone with commit or triage rights may also nominate a user to be
invited to join the triage team.</p>
</div>
<div class="section" id="triaging-operations-for-members-of-the-core-and-triage-teams">
<h2>Triaging operations for members of the core and triage teams<a class="headerlink" href="#triaging-operations-for-members-of-the-core-and-triage-teams" title="Permalink to this headline">¶</a></h2>
<p>In addition to the above, members of the core team and the triage team
can do the following important tasks:</p>
<ul class="simple">
<li>Update labels for issues and PRs: see the list of <a class="reference external" href="https://github.com/matplotlib/matplotlib/labels">available github
labels</a>.</li>
<li>Triage issues:<ul>
<li><strong>reproduce the issue</strong>, if the posted code is a bug label the issue
with "status: confirmed bug".</li>
<li><strong>identify regressions</strong>, 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".</li>
<li><strong>close usage questions</strong> and politely point the reporter to use
<a class="reference external" href="https://discourse.matplotlib.org">discourse</a> or Stack Overflow
instead and label as "community support".</li>
<li><strong>close duplicate issues</strong>, after checking that they are
indeed duplicate. Ideally, the original submitter moves the
discussion to the older, duplicate issue</li>
<li><strong>close issues that cannot be replicated</strong>, after leaving time (at
least a week) to add extra information</li>
</ul>
</li>
</ul>
<div class="topic">
<p class="topic-title">Closing issues: a tough call</p>
<p>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.</p>
</div>
</div>
<div class="section" id="a-typical-workflow-for-triaging-issues">
<h2>A typical workflow for triaging issues<a class="headerlink" href="#a-typical-workflow-for-triaging-issues" title="Permalink to this headline">¶</a></h2>
<p>The following workflow <a class="footnote-reference" href="#id3" id="id2">[1]</a> is a good way to approach issue triaging:</p>
<ol class="arabic">
<li><p class="first">Thank the reporter for opening an issue</p>
<p>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.</p>
</li>
<li><p class="first">Is this a usage question? If so close it with a polite message.</p>
</li>
<li><p class="first">Is the necessary information provided?</p>
<p>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.</p>
</li>
<li><p class="first">Is the issue minimal and reproducible?</p>
<p>For bug reports, we ask that the reporter provide a minimal
reproducible example. See <a class="reference external" href="https://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports">this useful post</a>
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.</p>
<p>If a reproducible example is provided, but you see a simplification,
add your simpler reproducible example.</p>
<p>If you can not reproduce the issue, please report that along with your
OS, Python, and Matplotlib versions.</p>
<p>If we need more information from either this or the previous step
please label the issue with "status: needs clarification".</p>
</li>
<li><p class="first">Is this a regression?</p>
<p>While we strive for a bug-free library, regressions are the highest
priority. If we have broken user-code that <em>used to</em> work, we should
fix that in the next patch release!</p>
<p>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 <a class="reference external" href="https://git-scm.com/docs/git-bisect">git bisect</a> to find the first commit
where it was broken.</p>
</li>
<li><p class="first">Is this a duplicate issue?</p>
<p>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.</p>
<p>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.</p>
<p>Label the closed issue with "status: duplicate"</p>
</li>
<li><p class="first">Make sure that the title accurately reflects the issue. If you have the
necessary permissions edit it yourself if it's not clear.</p>
</li>
<li><p class="first">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, ...</p>
<p>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).</p>
<p>An additional useful step can be to tag the corresponding module e.g.
the "GUI/Qt" label when relevant.</p>
</li>
</ol>
<table class="docutils footnote" frame="void" id="id3" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id2">[1]</a></td><td>Adapted from the pandas project <a class="reference external" href="https://dev.pandas.io/docs/development/maintaining.html">maintainers guide</a> and
<a class="reference external" href="https://scikit-learn.org/dev/developers/bug_triaging.html">the scikit-learn project</a> .</td></tr>
</tbody>
</table>
</div>
<div class="section" id="working-on-prs-to-help-review">
<h2>Working on PRs to help review<a class="headerlink" href="#working-on-prs-to-help-review" title="Permalink to this headline">¶</a></h2>
<p>Reviewing code is also encouraged. Contributors and users are welcome to
participate to the review process following our <a class="reference internal" href="coding_guide.html#pr-guidelines"><span class="std std-ref">review guidelines</span></a>.</p>
</div>
<div class="section" id="acknowledgments">
<h2>Acknowledgments<a class="headerlink" href="#acknowledgments" title="Permalink to this headline">¶</a></h2>
<p>This page is lightly adapted from <a class="reference external" href="https://scikit-learn.org/dev/developers/bug_triaging.html">the sckit-learn project</a> .</p>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<footer>
<div class="footer">
© Copyright 2002 - 2012 John Hunter, Darren Dale, Eric Firing, Michael Droettboom and the Matplotlib development team; 2012 - 2021 The Matplotlib development team.
<br />
Last updated on May 08, 2021.
Created using
<a href="http://sphinx-doc.org/">Sphinx</a> 3.2.1.
Doc version v3.4.2-2-gf801f04d09-dirty.
</div>
</footer>
</body>
</html>