Debian Codegraph @

docs/internals/contributing/triaging-tickets.txt

raw
1 ================
2 Triaging tickets
3 ================
4
5 Django uses Trac_ for managing the work on the code base. Trac is a
6 community-tended garden of the bugs people have found and the features Django
7 has decided to add. As in any garden, sometimes there are weeds to be pulled
8 and sometimes there are flowers and vegetables that need picking. We need your
9 help to sort out one from the other, and in the end, we all benefit together.
10
11 Like all gardens, we can aspire to perfection, but in reality there's no such
12 thing. Even in the most pristine garden there are still snails and insects.
13 In a community garden there are also helpful people who -- with the best of
14 intentions -- fertilize the weeds and poison the roses. It's the job of the
15 community as a whole to self-manage, keep the problems to a minimum, and
16 educate those coming into the community so that they can become valuable
17 contributing members.
18
19 Similarly, while we aim for Trac to be a perfect representation of the state of
20 Django's progress, we acknowledge that this will not happen. By distributing
21 the load of Trac maintenance to the community, we accept that there will be
22 mistakes. Trac is "mostly accurate", and we give allowances for the fact that
23 sometimes it will be wrong. That's okay. We're perfectionists with deadlines.
24
25 We rely on the community to keep participating, keep tickets as accurate as
26 possible, and raise issues for discussion on the `Django Forum`_ when there is
27 confusion or disagreement.
28
29 Django is a community project, and every contribution helps. We can't do this
30 without **you**!
31
32 Triage workflow
33 ===============
34
35 Unfortunately, not all reports in the ticket tracker provide all the
36 :doc:`required details<bugs-and-features>`. A number of tickets have proposed
37 solutions, but those don't necessarily meet all the requirements :ref:`adhering
38 to the guidelines for contributing <patch-style>`.
39
40 One way to help out is to *triage* tickets that have been created by other
41 users.
42
43 Most of the workflow is based around the concept of a ticket's
44 :ref:`triage stages <triage-stages>`. Each stage describes where in its
45 lifetime a given ticket is at any time. Along with a handful of flags, this
46 attribute easily tells us what and who each ticket is waiting on.
47
48 Since a picture is worth a thousand words, let's start there:
49
50 .. image:: /internals/_images/triage_process.*
51 :height: 750
52 :width: 600
53 :alt: Django's ticket triage workflow
54
55 We've got two roles in this diagram:
56
57 * Mergers: people with commit access who are responsible for making the
58 final decision to merge a change.
59
60 * Ticket triagers: anyone in the Django community who chooses to
61 become involved in Django's development process. Our Trac installation
62 is intentionally left open to the public, and anyone can triage tickets.
63 Django is a community project, and we encourage :ref:`triage by the
64 community<how-can-i-help-with-triaging>`.
65
66 By way of example, here we see the lifecycle of an average ticket:
67
68 * Alice creates a ticket and sends an incomplete pull request (no tests,
69 incorrect implementation).
70
71 * Bob reviews the pull request, marks the ticket as "Accepted", "needs tests",
72 and "patch needs improvement", and leaves a comment telling Alice how the
73 patch could be improved.
74
75 * Alice updates the pull request, adding tests (but not changing the
76 implementation). She removes the two flags.
77
78 * Charlie reviews the pull request and resets the "patch needs improvement"
79 flag with another comment about improving the implementation.
80
81 * Alice updates the pull request, fixing the implementation. She removes the
82 "patch needs improvement" flag.
83
84 * Daisy reviews the pull request and marks the ticket as "Ready for checkin".
85
86 * Jacob, a :ref:`merger <mergers-team>`, reviews the pull request and merges
87 it.
88
89 Some tickets require much less feedback than this, but then again some tickets
90 require much much more.
91
92 .. _triage-stages:
93
94 Triage stages
95 =============
96
97 Below we describe in more detail the various stages that a ticket may flow
98 through during its lifetime.
99
100 Unreviewed
101 ----------
102
103 The ticket has not been reviewed by anyone who felt qualified to make a
104 judgment about whether the ticket contained a valid issue or ought to be closed
105 for any of the various reasons.
106
107 Accepted
108 --------
109
110 The big gray area! The absolute meaning of "accepted" is that the issue
111 described in the ticket is valid and is in some stage of being worked on.
112 Beyond that there are several considerations:
113
114 * **Accepted + No Flags**
115
116 The ticket is valid, but no one has submitted a patch for it yet. Often this
117 means you could safely start writing a fix for it. This is generally more
118 true for the case of accepted bugs than accepted features. A ticket for a bug
119 that has been accepted means that the issue has been verified by at least one
120 triager as a legitimate bug - and should probably be fixed if possible.
121
122 For new features, accepted tickets should only exist after the idea has gone
123 through the appropriate :ref:`process for suggesting new features
124 <requesting-features>` and received community and :ref:`Steering Council
125 <steering-council>` approval, or been accepted in a DEP.
126
127 * **Accepted + Has Patch**
128
129 The ticket is waiting for people to review the supplied solution. This means
130 downloading the patch and trying it out, verifying that it contains tests
131 and docs, running the test suite with the included patch, and leaving
132 feedback on the ticket.
133
134 * **Accepted + Has Patch + Needs ...**
135
136 This means the ticket has been reviewed, and has been found to need further
137 work. "Needs tests" and "Needs documentation" are self-explanatory. "Patch
138 needs improvement" will generally be accompanied by a comment on the ticket
139 explaining what is needed to improve the code.
140
141 Ready For Checkin
142 -----------------
143
144 The ticket was reviewed by any member of the community other than the person
145 who supplied the patch and found to meet all the requirements for a
146 commit-ready contribution. A :ref:`merger <mergers-team>` now needs to give
147 a final review prior to being committed.
148
149 There are a lot of pull requests. It can take a while for your patch to get
150 reviewed. See the :ref:`contributing code FAQ<new-contributors-faq>` for some
151 ideas here.
152
153 Someday/Maybe
154 -------------
155
156 This stage isn't shown on the diagram. It's used sparingly to keep track of
157 long-term changes.
158
159 These tickets are uncommon and overall less useful since they don't describe
160 concrete actionable issues.
161
162 Other triage attributes
163 =======================
164
165 A number of flags, appearing as checkboxes in Trac, can be set on a ticket:
166
167 Has patch
168 ---------
169
170 This means the ticket has an associated solution. These will be reviewed to
171 ensure they adhere to the :doc:`documented guidelines
172 <writing-code/submitting-patches>`.
173
174 The following three fields (Needs documentation, Needs tests,
175 Patch needs improvement) apply only if a patch has been supplied.
176
177 Needs documentation
178 -------------------
179
180 This flag is used for tickets with patches that need associated
181 documentation. Complete documentation of features is a prerequisite
182 before we can check them into the codebase.
183
184 Needs tests
185 -----------
186
187 This flags the patch as needing associated unit tests. Again, this
188 is a required part of a valid contribution.
189
190 Patch needs improvement
191 -----------------------
192
193 This flag means that although the ticket *has* a solution, it's not quite
194 ready for checkin. This could mean the patch no longer applies
195 cleanly, there is a flaw in the implementation, or that the code
196 doesn't meet our standards.
197
198 Easy pickings
199 -------------
200
201 Tickets that would require small, easy, changes.
202
203 Type
204 ----
205
206 Tickets should be categorized by *type* between:
207
208 * New Feature
209 For adding something new.
210
211 * Bug
212 For when an existing thing is broken or not behaving as expected.
213
214 * Cleanup/optimization
215 For when nothing is broken but something could be made cleaner,
216 better, faster, stronger.
217
218 Component
219 ---------
220
221 Tickets should be classified into *components* indicating which area of
222 the Django codebase they belong to. This makes tickets better organized and
223 easier to find.
224
225 Severity
226 --------
227
228 The *severity* attribute is used to identify blockers, that is, issues that
229 should get fixed before releasing the next version of Django. Typically those
230 issues are bugs causing regressions from earlier versions or potentially
231 causing severe data losses. This attribute is quite rarely used and the vast
232 majority of tickets have a severity of "Normal".
233
234 Version
235 -------
236
237 It is possible to use the *version* attribute to indicate in which
238 version the reported bug was identified.
239
240 UI/UX
241 -----
242
243 This flag is used for tickets that relate to User Interface and User
244 Experiences questions. For example, this flag would be appropriate for
245 user-facing features in forms or the admin interface.
246
247 Cc
248 --
249
250 You may add your username or email address to this field to be notified when
251 new contributions are made to the ticket.
252
253 Keywords
254 --------
255
256 With this field you may label a ticket with multiple keywords. This can be
257 useful, for example, to group several tickets on the same theme. Keywords can
258 either be comma or space separated. Keyword search finds the keyword string
259 anywhere in the keywords. For example, clicking on a ticket with the keyword
260 "form" will yield similar tickets tagged with keywords containing strings such
261 as "formset", "modelformset", and "ManagementForm".
262
263 .. _closing-tickets:
264
265 Closing Tickets
266 ===============
267
268 When a ticket has completed its useful lifecycle, it's time for it to be
269 closed. Closing a ticket is a big responsibility, though. You have to be sure
270 that the issue is really resolved, and you need to keep in mind that the
271 reporter of the ticket may not be happy to have their ticket closed (unless
272 it's fixed!). If you're not certain about closing a ticket, leave a comment
273 with your thoughts instead.
274
275 If you do close a ticket, you should always make sure of the following:
276
277 * Be certain that the issue is resolved.
278
279 * Leave a comment explaining the decision to close the ticket.
280
281 * If there is a way they can improve the ticket to reopen it, let them know.
282
283 * If the ticket is a duplicate, reference the original ticket. Also
284 cross-reference the closed ticket by leaving a comment in the original one
285 -- this allows to access more related information about the reported bug
286 or requested feature.
287
288 * **Be polite.** No one likes having their ticket closed. It can be
289 frustrating or even discouraging. The best way to avoid turning people
290 off from contributing to Django is to be polite and friendly and to offer
291 suggestions for how they could improve this ticket and other tickets in
292 the future.
293
294 A ticket can be resolved in a number of ways:
295
296 * fixed
297 Used once a patch has been rolled into Django and the issue is fixed.
298
299 * invalid
300 Used if the ticket is found to be incorrect. This means that the
301 issue in the ticket is actually the result of a user error, or
302 describes a problem with something other than Django, or isn't
303 a bug report or feature request at all (for example, some new users
304 submit support queries as tickets).
305
306 * wontfix
307 Used when someone decides that the request isn't appropriate for
308 consideration in Django. Sometimes a ticket is closed as "wontfix" with a
309 request for the reporter to start a discussion on the `Django Forum`_ if
310 they feel differently from the rationale provided by the person who
311 closed the ticket. Other times, a discussion precedes the decision to
312 close a ticket. Always use the forum to get a consensus before reopening
313 tickets closed as "wontfix".
314
315 * duplicate
316 Used when another ticket covers the same issue. By closing duplicate
317 tickets, we keep all the discussion in one place, which helps
318 everyone.
319
320 * worksforme
321 Used when the ticket doesn't contain enough detail to replicate
322 the original bug.
323
324 * needsinfo
325 Used when the ticket does not contain enough information to replicate
326 the reported issue but is potentially still valid. The ticket
327 should be reopened when more information is supplied.
328
329 If you believe that the ticket was closed in error -- because you're
330 still having the issue, or it's popped up somewhere else, or the triagers have
331 made a mistake -- please reopen the ticket and provide further information.
332 Again, please do not reopen tickets that have been marked as "wontfix" and
333 bring the issue to the `Django Forum`_ instead.
334
335 .. _how-can-i-help-with-triaging:
336
337 How can I help with triaging?
338 =============================
339
340 The triage process is primarily driven by community members. Really,
341 **ANYONE** can help.
342
343 To get involved, start by `creating an account on Trac`_. If you have an
344 account but have forgotten your password, you can reset it using the `password
345 reset page`_.
346
347 Then, you can help out by:
348
349 * Closing "Unreviewed" tickets as "invalid", "worksforme", or "duplicate", or
350 "wontfix".
351
352 * Closing "Unreviewed" tickets as "needsinfo" when the description is too
353 sparse to be actionable.
354
355 * Correcting the "Needs tests", "Needs documentation", or "Has patch"
356 flags for tickets where they are incorrectly set.
357
358 * Setting the "`Easy pickings`_" flag for tickets that are small and
359 relatively straightforward.
360
361 * Set the *type* of tickets that are still uncategorized.
362
363 * Checking that old tickets are still valid. If a ticket hasn't seen
364 any activity in a long time, it's possible that the problem has been
365 fixed but the ticket hasn't yet been closed.
366
367 * Identifying trends and themes in the tickets. If there are a lot of bug
368 reports about a particular part of Django, it may indicate we should
369 consider refactoring that part of the code. If a trend is emerging,
370 you should raise it for discussion (referencing the relevant tickets)
371 on the `Django Forum`_.
372
373 * Verify if solutions submitted by others are correct. If they are correct
374 and also contain appropriate documentation and tests then move them to the
375 "Ready for Checkin" stage. If they are not correct then leave a comment to
376 explain why and set the corresponding flags ("Patch needs improvement",
377 "Needs tests" etc.).
378
379 .. note::
380
381 The `Reports page`_ contains links to many useful Trac queries, including
382 several that are useful for triaging tickets and reviewing proposals as
383 suggested above.
384
385 You can also find more :doc:`new-contributors`.
386
387 .. _Reports page: https://code.djangoproject.com/wiki/Reports
388
389 However, we do ask the following of all general community members working in
390 the ticket database:
391
392 * Please **don't** promote your own tickets to "Ready for checkin". You
393 may mark other people's tickets that you've reviewed as "Ready for
394 checkin", but you should get at minimum one other community member to
395 review a patch that you submit.
396
397 * Please **don't** reverse a decision without posting a message to the
398 `Django Forum`_ to find consensus.
399
400 * If you're unsure if you should be making a change, don't make the
401 change but instead leave a comment with your concerns on the ticket,
402 or post a message to the `Django Forum`_. It's okay to be unsure, but your
403 input is still valuable.
404
405 .. _Trac: https://code.djangoproject.com/
406 .. _`easy pickings`: https://code.djangoproject.com/query?status=!closed&easy=1
407 .. _`creating an account on Trac`: https://www.djangoproject.com/accounts/register/
408 .. _password reset page: https://www.djangoproject.com/accounts/password/reset/
409 .. _Django Forum: https://forum.djangoproject.com/
410
411 Bisecting a regression
412 ======================
413
414 A regression is a bug that's present in some newer version of Django but not in
415 an older one. An extremely helpful piece of information is the commit that
416 introduced the regression. Knowing the commit that caused the change in
417 behavior helps identify if the change was intentional or if it was an
418 inadvertent side-effect. Here's how you can determine this.
419
420 Begin by writing a regression test for Django's test suite for the issue. For
421 example, we'll pretend we're debugging a regression in migrations. After you've
422 written the test and confirmed that it fails on the latest main branch, put it
423 in a separate file that you can run standalone. For our example, we'll pretend
424 we created ``tests/migrations/test_regression.py``, which can be run with:
425
426 .. code-block:: shell
427
428 $ ./runtests.py migrations.test_regression
429
430 Next, we mark the current point in history as being "bad" since the test fails:
431
432 .. code-block:: shell
433
434 $ git bisect bad
435 You need to start by "git bisect start"
436 Do you want me to do it for you [Y/n]? y
437
438 Now, we need to find a point in git history before the regression was
439 introduced (i.e. a point where the test passes). Use something like
440 ``git checkout HEAD~100`` to check out an earlier revision (100 commits earlier,
441 in this case). Check if the test fails. If so, mark that point as "bad"
442 (``git bisect bad``), then check out an earlier revision and recheck. Once you
443 find a revision where your test passes, mark it as "good":
444
445 .. code-block:: shell
446
447 $ git bisect good
448 Bisecting: X revisions left to test after this (roughly Y steps)
449 ...
450
451 Now we're ready for the fun part: using ``git bisect run`` to automate the rest
452 of the process:
453
454 .. code-block:: shell
455
456 $ git bisect run tests/runtests.py migrations.test_regression
457
458 You should see ``git bisect`` use a binary search to automatically checkout
459 revisions between the good and bad commits until it finds the first "bad"
460 commit where the test fails.
461
462 Now, report your results on the Trac ticket, and please include the regression
463 test as an attachment. When someone writes a fix for the bug, they'll already
464 have your test as a starting point.