Dan Connolly's tinkering lab notebook

Setting up project tracking with trac, hg, and a little help from my friends on freenode

We're hiring! Interested? Apply for the Biomedical Informatics Software Engineer position.

One of my first tasks here was setting up version control. The guy who hired me, Russ, had experience with svn and especially TracBrowser and was aware of the trend toward distributed version control. While git has a 1st-mover advantage and bzr is maturing, I have been using mercurial (hg) since before github and the like made git's user interface tolerable and before bzr's performance was acceptable. Between Joel Spolsky's excellent Hg Init tutorial and the TortoiseHg windows shell integration, it wasn't hard to get mercurial adopted as our version control system.

Of the three, bzr is the only one that does 1st-class renames (including directories); I'm betting we won't need to cross that bridge for some time.

Mercurial's limitations around big files never bothered me before; I formed my version control habits with CVS, which handles binary files about as well as my teenage boys handle vegetables: only when given very specific instructions and even then, not gracefully. But there are a lot of Microsoft Office documents around here, this being an enterprise with largely pre-web computing norms. As a web guy, my sentiments are largely with Edd:

But really, office documents make me cry.

-- Platform agnostic productivity - once bitten

But that's where the information is, so I took a few a MS Word documents and put them in our mercurial repository. Once I realized what a hassle it would be to merge diffs in MS Word documents (is it even possible?) I realized it made more sense to put them in our trac wiki as attachments.

Trac turns out to be a great fit for our group. I knew from experience that bugzilla is a hassle that's only worthwhile in communities several orders of magnitude larger than ours. My other experience was with roundup, whose web interface is so smooth that you can just about capture status at the rate  developers discuss issues around a table. I knew that I wanted an issue tracking system, but I wasn't sure whether the integrated wiki and source code browsers would help us out or just get in the way. The wiki turns out to be a great catalyst for the switch from mailing copies around at each iteration to working in a shared web space. MS Word documents can be thrown in as attachments at first and migrated to hypertext in due course.

At first the tickets were just a way for me to track my own work, but we're getting pretty good at using trac for an approximation of the XP planning game: Russ plays business customer and I represent development. Sometimes sketching milestones and breaking them down into tickets is straightforward enough, but sometimes I don't understand what he's asking for, so I ask him to tell me stories about how it works, and we capture those in the wiki.

It's working well enough that some people are considering it as an alternative to MS Sharepoint in a few cases. I wonder how the cost of setting sharepoint compares to what I've been through with trac:

  • The initial stand-alone installation of trac worked fine, but when I tried to integrate it with apache via mod_wsgi, I ran into shared library conflicts. Fortunately, IssuesWithExpatLibrary are well documented and the fix was just:
    • sudo zypper install libexpat-devel
      zypper? what's that? It's the SuSE equivalent to apt-get. The enterprise investment in Novell spills over into using SuSE linux rather than debian or Ubuntu.
    • rebuild apache with --with-expat=/usr/lib
  • Trac has a traccas plug-in for the campus single sign-on system, CAS. I ran into redirect loops when I first set it up; not to fear: it's a a known bug (ticket 4025) and the fix was just to give  repository_dir a good value in the trac.ini configuration file.
  • In one of the projects here, we provide requirements to a vendor. To help track which requirements are satisfied by a recent code drop, I took the MS Word document with the current table of requirements, saved it as HTML, tidied it, shuffled the columns around a bit with a 50-line python script, and imported it with the TicketImport plug-in (which is really great because it can do updates as well as inserts).
    • It seemed a little silly to use .xls rather than .csv for the import, but the data had unicode quotes and the xlwt package is unicode-happy while python's csv module isn't.
  • One of the services provided by our department has an established workflow. I'm experimenting with representing it in trac. I added a custom ticket type and used the MultipleWorkflow plug-in to give it a custom workflow. The jury is still out on whether we'll adopt trac to manage this service.

The difference in license fees is easy enough to compute: it's whatever sharepoint costs minus zero, since all of the above is free software. Perhaps I spent more time setting it up than sharepoint administrators do, but I suspect that even so, there's some leftover that I should arrange to donate to freenode, which provides discussion facilities: the #trac channel (thanks coderanger!) and #mercurial and #pythonpaste and #httpd and #suse. Next time you're stuck or you just want to bounce ideas off others that are likely to be interested, give it a try.