By Cal Henderson, March 22nd 2010.
(In which I expand on this tweet with some details).
Issue tracking (or bug tracking, or whatever you want to call it) is an all too often overlooked piece of the development toolset. Having a bad issue tracking system will make your software worse. You will have fewer bugs filed. You are more likely to get duplicate bugs. People will hate you. Please stop doing it.
WebSVN is a nice piece of software written in PHP to browse local and remote SVN repositories. It's much easier to use than its Perl, Python or Ruby friends because it doesn't require SVN language bindings, which are close to impossible to compile from scratch. It's quite a pretty piece of software too; looks good, easy to use.
When I had an issue with it, I visited the project website, and then found the issue tracker under "Contribute". The link on this page for the issue tracker then takes you to an entirely different site with this awesome page:
How do a report an issue? No idea at all. Following each of these links does not help. After giving up and coming back to it later, I wonder if maybe I have to log in first? I give that a try, and then come back to the same page:
Bingo! Good job for letting me know, guys. What am I entering? I figure it's probably a defect, but what's the difference between a defect and a task? What's a feature versus an enhancement? And to report a bug I need to be a project member (what does that mean? how do I become one?) and know the component I want to report on (what does that mean?). I guess I'll click on defect and see how it goes.
Holy mother of god, I hate this form. I don't understand the sub components. Platform and OS seem hugely redundant. Why does it default to the oldest version? How do I know what priority this bug is? Who should I assign it to? Or CC? What is the URL field for? Why do forms ever have a fucking reset button? Just in case I wanted to accidentally wipe everything I entered? Why does it tell me that it used my user agent to initialize fields, when it clearly didn't? Hateful.
I understand that some projects like to have a hugely complicated bug tracking system, but that doesn't mean you need to push all of those settings onto every person who reports a bug. Even Mozilla now have a much more streamlined bug filing process. There is no excuse for this in 2010.
So if that's bad, what is good? Github is all the rage with the kids these days, but it turns out it's actually pretty awesome. I found an issue with Facebook's Scribe project, so I visited the project web page. There's an "Issues" link right in the main navigation, so I click that:
Seems simple enough - on the top left there's a "Create Issue" button, not hidden away. Clicking on it takes me right to a login page:
While it doesn't explicitly tell me that I need to log in to file a bug, it seems pretty obvious. So I go ahead and do that and am presented with the pinnacle of bug reporting forms:
A title and description. And a quick search for previous issues. That's it. Just report the bug. I don't need to understand how their development team is organized, how they handle priorities, or what they call individual parts of the software.
Behind the scenes (from my point of view) these tools can be as powerful and complex as the developers like. Just don't make me learn your particular system to let you know about bugs.
I write things too fast and don't spend enough time checking my work - If you spot any glaring mistakes or omissions, drop me an email and make me look dumb: cal [at] iamcal.com
Copyright © 2010 Cal Henderson.
The text of this article is all rights reserved. No part of these publications shall be reproduced, stored in a retrieval system, or transmitted by any means - electronic, mechanical, photocopying, recording or otherwise - without written permission from the publisher, except for the inclusion of brief quotations in a review or academic work.