In The Toolbox - Feature Tracking

 

A common question that comes up on the accu-general mailing list is about the tools teams can use to track the list of features being implemented for their product. Depending on the size of the team, the maturity of the product and the enterprise-ness of the organisation Iíve used a number a tools in the past. Other factors that have affected my opinion of the usefulness of a tool have often revolved around how it gels with the other tools such as the version control system.

 

For my own personal set of libraries and applications I naturally have very simple needs. Generally speaking all I want is a one line description of a bug or feature. Consequently every library and application has a simple text file called TODO.txt that is (often) an unordered list of features. One of the good things about keeping this file in the repo alongside the source code is that it changes as each feature is implemented. Generating the release notes is then as simple as picking out all the diffs of that file since the last release label.

 

More recently Iíve started using an online service (GitHub) to host my source code repos. Being a service aimed at project hosting, each repo automatically gains an Issues database and Wiki. The database of issues provides the next step up from a simple text file as you can track the status of features in more detail, such as whoís assigned to it, which release itís destined for, etc. Because itís integrated with the source code repo including a number such as ď#42Ē in the commit message creates a link in the GitHub UI to the issue with the same number which is good for software archaeology later.

 

At the other end of the spectrum are the Enterprise scale products that try to cater for big teams with heavy development processes that feel the need to try and track lots of ďimportantĒ metrics about each feature. They often come as part of a big suite that plays on their integration as a selling point. For example itís possible (and incredibly annoying) that Rationalís ClearCase version control product supports triggers that ensure a change canít be committed unless itís linked to an item in ClearQuest, their feature tracking database.

 

Itís a noble pursuit to try and ensure that every code change, and therefore every commit, is related in some way to a formally tracked feature, whether instigated by the business or the development team itself, as that helps keep everyone honest. However I find enforcing that kind of policy increases the pain of checking in out-of-band changes, such as to the build process, and only succeeds in enticing developers to bundle unrelated changes instead. If the tool makes adding a new feature request tedious then itís not going to be used the way you might prefer.

 

Outside the realm of dedicated 3rd party feature tracking products are the home grown alternatives. Naturally Excel, the Swiss-army knife of the corporate world, has been pressed into service on many an occasion. Despite it being painful to enter or read blocks of text with more than a couple of words, its ability to easily produce charts seems to be a big consolation prize in some circles. The agile project managerís fascination with burn-down charts and the like might fuel this choice.

 

What is probably the most derided part of the Microsoft Office suite Ė the Access database tool Ė is far more suited to the task, or at least was a decade or so ago. The only time Iíve ever actually created a database in Access was to knock up a simple bug tracking database for a very small team I was in. Iíd seen someone do it before at another site Iíd worked at and when the team grew large enough for the single-user problems to start becoming a drag it was easy to migrate the underlying database engine to something more heavy-duty, like SQL Server. With the plethora of free options available today the days of writing your own issue tracker have almost certainly long gone.

 

In more recent times Iíve had the pleasure of using another of the Enterprise favourites Ė JIRA. I appear to have been quite lucky in that my team were using it how they wanted to, rather than how the project manager might want to. This meant we kept the ceremony fairly low by only tracking features at a high-ish level, linking them where appropriate and introducing sub-tasks when the larger features spanned multiple releases. JIRA can parse the check-in comments to relate source changes to a feature and supports links and attachments which are useful for relating associated documentation, such as design notes, email discussions, manual test cases, etc.

 

At the TICOSA conference [1] I mentioned in the last edition of this column [2] there was an interesting question about where to store the supporting documentation for a feature. Whilst the code might be a good place to document some specific details about the current implementation, it isnít necessarily the best place to ďRecord Your RationaleĒ [3]. For this a wiki might be more appropriate or, if the document requires some richer content such as UML sketches, then storing them in the repo itself in a separate docs folder also keeps them close to hand.

 

The last 12 months has seen me working on a number of greenfield projects. Our very small team only needed a simple tool that would allow easy manipulation of stories rather than containing any notably lengthy text. In each case we used Trello and found it to be more than adequate. In fact after being forced briefly to use an in-house SharePoint-based imitation we soon realised how much we missed it! The text in cards can be written using Markdown for a little extra spice, can contain attachments, and checklists which are an excellent way to tick off the ďdone, doneĒ criteria. Cards also have a unique number which can be referenced in the commit messages. On one project board we had a column named after each release version and using the JSON export feature of Trello and JQ (a JSON command-line query tool) I produced some release notes automatically based on the card number and title.

 

Whilst a project managerís perspective of a feature tracking tool will likely be biased towards prioritisation and progress, as a developer I find I have different perspectives depending on the state of the feature. Prior to implementation I also want to know what the most important feature is along with details of acceptance criteria, etc. Post implementation Iím often looking for a way to trace a change in the source code back out to the driver for it so that I can better understand its context. This helps makes subsequent changes a little safer, especially when tests are scarce such as in legacy codebases. Sometimes, such as when a serious piece of technical debt has been accrued, I raise a ticket and embed the ticket number directly in the code to make it easier for a future maintenance programmer to track down the supporting notes in case Iím not around when they finally decide to pay it back.

References

[1] http://www.ticosa.org

[2] C Vu 26-1, March 2014

[3] http://architect.97things.oreilly.com/wiki/index.php/Record_your_rationale

 

Chris Oldwood

15 June 2014

 

Bio

Chris is a freelance developer who started out as a bedroom coder in the 80ís writing assembler on 8-bit micros; these days itís C++ and C#. He also commentates on the Godmanchester duck race and can be contacted via gort@cix.co.uk or @chrisoldwood.