Filing a Good Ticket
I read just about every single ticket that’s filed in Django’s trac, and at this point I’e gotten a pretty good sense of what (subjectively) makes a useful ticket. Specifically there are a few things that can make your ticket no better than spam, and a few that can instantly bump your ticket to the top of my “TODO” list. Hopefully, these will be helpful in both filing ticket’s for Django as well as other open source projects.
- Search for a ticket before filing a new one. Django’s trac, for example, has at least 10 tickets describing “Decoupling urls in the tutorial, part 3”. These have all been wontfixed (or closed as a duplicate of one of the others). Each time one of these is filed it takes time for someone to read through it, write up an appropriate closing message, and close it. Of course, the creator of the ticket also invested time in filing the ticket. Unfortunately, for both parties this is time that could be better spent doing just about anything else, as the ticket has been decisively dealt with plenty of times.
- On a related note, please don’t reopen a ticket that’s been closed before. This one depends more on the policy of the project, in Django’s case the policy is that once a ticket has been closed by a core developer the appropriate next step is to start a discussion on the development mailing list. Again this results in some wasted time for everyone, which sucks.
- Read the contributing documentation. Not every project has something like this, but when a project does it’s definitely the right starting point. It will hopefully contain useful general bits of knowledge (like what I’m trying to put here) as well as project specific details, what the processes are, how to dispute a decision, how to check the status of a patch, etc.
- Provide a minimal test case. If I see a ticket who’s description involves a 30 field model, it drops a few rungs on my TODO list. Large blocks of code like this take more time to wrap ones head around, and most of it will be superfluous. If I see just a few lines of code it takes way less time to understand, and it will be easier to spot the origin of the problem. As an extension to this if the test case comes in the form of a patch to Django’s test suite it becomes even easier for a developer to dive into the problem.
- Don’t file a ticket advocating a major feature or sweeping change. Pretty much if it’s going to require a discussion the right place to start is the mailing list. Trac is lousy at facilitating discussions, mailing lists are designed explicitly for that purpose. A discussion on the mailing list can more clearly outline what needs to happen, and it may turn out that several tickets are needed. For example filing a ticket saying, “Add CouchDB support to the ORM” is pretty useless, this requires a huge amount of underlying changes to make it even possible, and after that a database backend can live external to Django, so there’s plenty of design decisions to go around.
These are some of the issues I’ve found to be most pressing while reviewing tickets for Django. I realize they are mostly in the “don’t” category, but filing a good ticket can sometimes be as good as clearly stating what the problem is, and how to reproduce it.