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 3^rd 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.