Iām jumping back and forth between working on my big āsecretā project and getting some good code into my pet project manager Darcsforge [1]. One of the oldest (now) pieces of Darcsforge is my pet issue tracker, nicknamed āorkinā, and it was time to renovate it to better fit with the later pieces Iāve worked on. One of the big things I re-debated was the use of āIssue Numbersā. Every Issue Tracker Iāve ever dealt with has used Issue Numbers as the main tool to reference an Issue [2]. The big Pro for Issue Numbers is their terseness: hundreds of thousands of issues can be addressed by a sequence of 6 numbers. The big Con: terseness. Sure you might be able to remember the difference between Issue 34 and Issue 43 but at a certain threshold you have to start referring to cheat sheets or the Issue Tracker itself to figure things out. Quick: Whatās the difference between Issue 135736 and Issue 135637? Issue numbers donāt work well for us people and are often much more artifacts of back-end systems (auto-numbered database primary keys) than artifacts for human consumption.
Django encourages web designers to design āhumaneā URLs. Take this blog site, for example, I could just as easily use /entry/343/, but I specifically chose the /2007/mar/14/issue-tracker-reference-schemes/ format because it says a lot more to the human mind and is a lot friendlier. It breaks into two major pieces, the posted date (3/14/2007 or March 14 2007 or whatever other mental format you prefer) and the āslugā, which is a newspaper term by way of Django, which in this case is issue-tracker-reference-schemes. The address there tells me when I posted the blog entry and something about the subject of the blog entry (at least in the cases where I pick a good and appropriate title for the entry, because the slug is just a cleaned, simplified version of the title I choose).
I decided that I would appreciate similar addresses in my issue tracker and starting questioning the usefulness of that as a general reference scheme. Certainly terseness is out the window, but is it memorable? I think so. Personally, I have an easier time remembering āthat issue from last monday involving integrating orkinā (Issue /2007/mar/11/get-orkin-integrated/) than some arbitrary number, and in fact thatās just about the way I mentally store that anyway. There is a deep context I pull from that reference: how old the issue is, a general idea of what the issue is about, and a general relationship between the issue and the projectās history (āin March feature x didnāt even exist and maybe x takes care of this issueā). All without having to actually open the issue or consult a cheat sheet.
So, one of the future features Iām obviously planning to get to is ādeep integrationā via reStructuredText similar to Tracās wiki-formatting. How does :issue:`2007-Mar-11 get-orkin-integrated` look for issue reference syntax? Basically Iām thinking Iām going to use āinterpreted rolesā in reST for Darcsforge intra-linking. For issues (and patches, and probably other things) Iām thinking of using the syntax [project] [date in YYYY-MMM-DD] slug. In many cases the slug alone should be sufficient (at least for me), and it can just grab the most recent, which will generally be the one you wantā¦
| [1] | An attempt at a Darcs oriented, Django based, Trac like project manager, but more modular/scalable |
| [2] | Iāve dealt with a lot of Issue Trackers. I can admit that Issue Trackers are well towards the top of the list of software development tools that are continually reinventedā¦ |