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