At AccuRev, we’ve noticed a new practice emerging that we call “Issue Based Development.” You may have heard of this term or something like it such as Work Item Based Development or even “requirements traceability.” Whatever you call it, more and more teams are gravitating towards it, perhaps as a result of adopting some of the Agile practices. In this post I will give an overview of Issue Based Development as well as talk about how to maximize your success with the practice.

Issue Based Development is the practice of breaking all work down into individual issues; associating all work products such as code, tests, and documentation with those issues; and managing the progression of work through the various stages of your software lifecycle via those issues.

The benefits of Issue Based Development include requirements traceability, better progress and status tracking, and simpler application of patches from one stream of development to another. These benefits and more will be covered as we cover the individual practices that make Issue Based Development possible.

Track All Work by Issues

Whether you have requirements, enhancement requests, escalations, defects, bugs, tasks, user stories, RFE’s or some other way to describe work, it all goes into issues. You may use a different term to generically describe tracked work, such as work items, but in this post I will use the term issues.

Today, many companies use some combination of Excel, Word, a Requirements Management system, a bug tracking system, MS Project, and an Agile Project Management tool to track “different” kinds of work. In the end though, somebody has to be assigned the work and that work needs to be explained to them in a way that makes sense to them. Why not use issues as the final unit of describing work, whether you continue to use the other systems or not?

Make All Issues Available in a Single Place

Using issues to describe and track all work implies that all issues for a particular project eventually end up in a single Issue Tracking System (ITS). The obvious way to achieve this is to simply move everybody to use the same ITS and to use it for all work-related artifacts, from defects to requirements to whatever else it is that you use. In reality this is difficult to achieve, but is the right goal to strive for, to the extent that you can.

Synchronize Multiple Work Tracking Systems

A good complement to moving as much work tracking to a single ITS system as possible is to synchronize issues from other work tracking systems to a single ITS system. For instance, AccuRev provides AccuBridge and AccuSync to enable you to have all of your work in a single system.

Link Issues to the Work Performed

Once you have all of your work tracked via issues in a single ITS, you are now ready to take the next step, linking all of your issues to the work performed to implement those issues. I’m assuming that you are keeping all of your work artifacts such as code, test, and documentation in your Software Configuration Management (SCM) system. The best way to link your issues to the work performed is to use an SCM object called a Change Package. Some systems may have a similar object called a change list or change set. AccuRev uses change packages.

By linking issues to work artifacts, you can now manage by issues instead of by files. For instance, instead of trying to figure out which files correspond to a set of hotfixes that you want to apply to new development, you can instead refer to the issues that represent those hotfixes and have the SCM system do all the hard work of determining the exact set of changes and promoting those changes from one environment to another.

Use a Stream Per Stage

Having a set of promotion stages is a great complement to Issue Based Development. By having a set of stages corresponding to your development workflow, you can easily see what stage of development various issues are really in simply by querying your SCM system. Doing reports against your ITS are good, but those are generally hand updated. Your SCM system reflects the real state of your code.

A typical set of stages might be “Todo,” “WIP,” “Coded,” “Tested,” and “Done.” You can represent each of these promotion stages with Streams in your SCM system. This allows you to associate Continuous Integration servers which each stage and build versions of your product corresponding to those stages. Imagine for instance being able to build a version of your product that has only tested stories in it.

Another benefit of this arrangement is that it enables “One Piece Flow.” For more on this topic, see my related (http://damonpoole.blogspot.com/2009/09/one-piece-flow-transitioning-from-scrum.html) DIY Agile blog post.

Keep Issues as Small as Possible

Most organizations are good at tracking all bugs in a bug-tracking system, but usually track new work via Word documents which describe very large chunks of work. When moving to Issue Based Development it is important to break these large chunks down into as many and as small issues as you possibly can. This is important for two reasons.

First, it is next to impossible to measure real progress against very large chunks of work. By breaking work down into small issues, it is easier to measure progress by seeing how many issues are fully coded, tested, documented, and ready to ship and measuring the amount of effort associated with those issues.

Second, working on small issues reduces the chances of “issue entanglement.” Entanglement occurs when two issues have changes that are dependent on each other in such a way that they become impossible to promote independently. The ideal is to have one person (or programming pair) work on a single issue at a time and for that issue to be finished in days rather than weeks. The more people working on an issue an the longer they are working on that issue, the more likely it is that the issue will become entangled with multiple other issues.

I’ve often heard people wonder why the SCM system can’t make this simpler. At AccuRev, we are always striving to make Change Packages simpler to use, but the simple fact is that there are limits to how much can be done to simplify entanglement issues. It is generally much more productive to apply the practices in this post which have benefits in and of themselves as described throughout.

Apply the Open/Closed Principle

Large files are another factor that contributes to issue entanglement. Often, frequently used and/or complex classes create large source files. This is similar to the problem of large issues. The larger a file is, the more likely it is that multiple people will be working on it within the same timeframe and thus the more likely it is to lead to issue entanglement.

There is a very useful principle that comes from Objected Oriented programming called the “Open/Closed” principle. This is the idea that software should be open to addition, but closed to change. In its pure form this means that you only add and extend classes and change them as a matter of last resort. A slightly modified version of this would be to only add new methods and to avoid changing them. Also, changing methods should be restricted to rewriting the code such that it adheres better to the principle by being easier to add new methods to and requiring less change to existing methods. This is a very common refactoring pattern.

The side-effect of the Open/Closed principle is that you end up with smaller source code files. The smaller your files are, the less likely you are to run into entanglement and merge issues.

Start Towards Issue Based Development Today

Whether you follow these principles and practices to the letter or not, the more you follow them, the easier it will be to practice Issue Based Development. The better you are at Issue Based Development, the more success you will have with requirements traceability, progress and status tracking, and the application of patches from one stream of development to another.