Issue tracker antipatterns

Robat Williams
Sep 5, 2018 · 6 min read

Update (Mar 2019): I published an updated and expanded version of this post over on the Scott Logic blog: Tips for effective issue tracker usage


Most projects use an issue tracking system to capture and track items of work through the development pipeline. The task at hand combined with the great configurability and feature sets of these tools leaves open many traps for users to fall into. Here are some to watch out for.

This is by no means definitive or comprehensive, and I’m not an expert in effective issue tracker usage. Some of them may work fine for you, and we all have our own preferences and tailored approaches to the different situations we work in.

I’ve picked them up over years of working on many projects in large organisations, mostly using Atlassian’s JIRA. Most of the items however are general.

They include that’s obvious things which apparently weren’t that obvious to some, gotchas and surprises, and longer term realisations.

The focus is on the use of an issue tracking system, so I won’t be venturing into the world of agile antipatterns.

One-size-fits-all configuration and workflow

Corporate JIRA instances sometimes assume that the same configuration of issue types, fields, statuses and workflows will suit all projects. Project-specific configuration changes, or permissions to make such changes, may take weeks — or not be possible. This can lead to projects using a configuration that doesn’t suit their needs/process, or that gets in their way.

A worse variant of this pitfall gives all project administrators permissions to modify configuration that is shared between all projects. Changes inevitably end up being made without consultation, accidentally or otherwise.

Single sprint board for all team roles

People with different roles in a project have different needs when it comes to viewing the status of issues in a sprint, which are not best served by using a single sprint board configuration. Such boards often end up configured to suit the needs of the most powerful stakeholders, at the expense of those who make the most use of the board. Having separate boards tailored to the needs of different roles (project manager/product owner, developers, etc.) allows each to have a setup that suits them best.

Unnecessarily long project key

Issue keys in JIRA (e.g. MYPROJ-123) uniquely identify issues (stories, bugs, etc.) in a project. The project key forms the first half, and uniquely identifies the project. Since issue keys are used frequently and in many locations, keeping them short allows quick typing and display in a reasonably-sized space.

Although it’s possible to change project keys at any time, their use in external integrations such as source control and build systems means that this is rarely done in practice. So pick a nice one from the start — short, meaningful, and recognisably distinct.

Note: the default setup of JIRA imposes a 10 character limit; this is often overridden to be longer in corporate installations.

Substituting Components for Epics

Epics are large pieces of work, which can be broken down into individual stories for prioritisation and development. These stories then belong to that epic. This relationship powers various useful features in JIRA including filters in the backlog view, and display of the epic name on sprint board issue cards.

Using components to group related stories together instead forgoes these features. This is typically semi-compensated for by prefixing the issue summary (title) with the component name, which adds clutter and causes the last (useful) part of the summary to be truncated in some views.

Using issue fields inconsistently

When a metadata field is used for different purposes by different team members, it’s no longer useful for any of them. For example, the “Fix version” may be set on issues as part of the release process, but also set by others with the version in which they desire an issue to be completed.

Starting sprints in the past

When starting a sprint, the default start time is the current time. You may be tempted to adjust this back to the start of the day, to reflect the official start time or just to be tidy. The problem with this is that all changes made to the sprint after that time (during sprint planning, for example) will feed in to all metrics and reports as within-sprint changes — making a mess of them.

Assuming labels are comprehensively applied

Labelling a set of issues with a certain label may give rise to the expectation that all issues that should be labelled as-such, are indeed labelled as-such. That may not always be the case, leading to missing out issues when filtering.

Not linking related issues

In addition to finding things when looking for them, team members are helped by being led to things they might want to look at together with what they were originally looking for. Creating links between issues makes this possible in both directions, for example depends-on, caused-by, relates-to, or duplicate-of.

Not recording reasons for actions

Issue history lets us see everything that’s happened to an issue so far — additions, changes, status changes, etc. What it doesn’t tell us is why those actions were made — why was this story removed mid-sprint, why was this bug rejected as won’t fix. An individual might remember it today, or remember they have an email from someone archived, but that’s not open or permanent. Adding comments fills in this gap, the same way they do in source code.

Recreating built-in functionality using labels

The flexibility and convenience of labels can lead to temptation to use them for purposes better served by existing built-in functionality. This includes use to track status (use the status field, configure additional statuses if needed) and priority (there’s a field for that too).

Recreating built-in functionality using Excel

Lists of issues are sometimes exported to Excel, usually for filtering or tracking a hit-list of critical ones. Both these use cases can be achieved using labels and filters, without deviating into a separate unconnected file.

Ignoring all notifications and emails

Participating in an issue tracker can easily lead to a deluge of emails in your inbox.

The most common solution to this problem is to set up a mail rule to delete them, or direct them to a folder — never to be read. The user then misses out on updates they’re interested in (new issues, comments, key status changes, etc.), which usually leads to team members being asked to personally communicate those updates to them manually/inefficiently.

A better approach is to set up more fine grained mail rules, filtering the emails into folders by type (or even just read/ignore). Simple string-contains rules on the subject and body are usually sufficient. Some trackers (GitHub) include a marker-address in the CC field with the notification reason for ease of filtering.

Rules can be exported from mail programs and shared with your team, lessening the setup effort and giving them a starting point to customise for their personal preferences.

Using the keyboard only for typing

Developers will be familiar with keyboard shortcuts in most of the tools they use, in order to improve productivity. That’s however not always the case for all members of the team. Helping less technical members out with some key shortcuts will save them time, and save everyone’s time when they’re in the driving seat during backlog refinement or sprint planning.

Dropping it under pressure

This one is on the edge of the agile antipatterns world. Under deadline pressure, a team may decide (or have it imposed on them) to drop all “unnecessary process” such as issue tracking and code review. Dropping the tracker tends to be a false economy — causing more time spent in manual communication and figuring-out of what is done/isn’t and what should go in the release notes. It also creates a gap in the history of the project.

Conclusion

I hope these can help you avoid some of the pitfalls I’ve encountered in your own projects. I’d love to hear of any others from your own experiences.

Software developer, web applications. @_rwms

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade