- -

- - index - -
- - dev - -
- - trackers-from-first-principles - -

- - - -

Bugs, Tasks, and Tickets from First Principles

Why do we track tasks?

To communicate about what should, will, has, and will not be done.
- Consequently, to either build consensus on what to do next or to dictate - it.
-
To measure and communicate progress.
To preserve information for future use.
- Otherwise we'd just remember it in our heads.
- Wishlist tasks are not a bad thing!
-

Bugs/defects are a kind of task but not the only kind. Most teams have a “bug -tracker” that contains a lot more than bugs. Let's not let bugs dictate the -system.

Therefore, “steps to reproduce” should not be a required datum.

Bugs are an important kind of task.

Tasks can be related to software development artifacts: commits, versions, -builds, releases.

A task may only be complete as of certain commits/releases/builds.
A task may only be valid after (or before) certain commits/releases/builds.

Communication loosely implies publishing. Tracking doesn't, but may rely on -the publishing of other facts.

Core Data

Tasks are only useful if they're actionable. To be actionable, they must be -understood. Understanding requires communication and documentation.

A protocol-agnostic name, for easily identifying a task in related - conversations.
- These names need to be short since they're used conversationally. Long - issue names will be shortened by convention whether the tracker supports - it or not.
-
An actionable description of the task.
- Frequently, a short summary of the task, to ease bulk task - manipulation. Think of the difference between an email subject and an - email body.
-
A discussion, consisting of remarks or comments, to track the evolving - understanding alongside the task.

See speciation, below.

Responsibility and Ownership

Regardless of whether your team operates with a top-down, command-oriented -management structure or with a more self-directed and anarchistic process, for -every task, there is notionally one person currently responsible for ensuring -that the task is completed.

That relationship can change over time; how it does so is probably -team-specific.

There may be other people involved in a task that are not responsible for -a task, in a number of roles. Just because I developed the code for a feature -does not mean I am necessarily responsible for the feature any more, but it -might be useful to have a “developed by” list for the feature's task.

Ways of identifying people:

Natural-language names (“Gianna Grady”)
Email addresses
Login names
Distinguished names in some directory
URLs

Task responsibility relationships reflect real-world responsibility, and help -communicate it, but do not normally define it.

Workflow

“Workflow” describes both the implications of the states a task can be in and -the implications of the transitions between states. Most task trackers are, at -their core, workflow engines of varying sophistication.

Why:

Improve shared understanding of how tracked tasks are performed.
Provide clear hand-off points when responsibility shifts.
Provide insight into which tasks need what kinds of attention.
Integration points for other behaviour.

States are implicitly time-bounded, and joined to their predecessor and -successor states by transitions.

Task state is decoupled from the real world: the task in a tracker is not the -work it describes.

Elemental states:

“Open”: in this state, the task has not yet been completed. Work may or may - not be ongoing.
“Completed”: in this state, all work on a task has been completed.
“Abandoned”: in this state, no further work on a task will be performed, but - the task has not been completed.

Most real-world workflows introduce some intermediate states that tie into -process-related handoffs.

For software, I see these divisions, in various combinations, frequently:

“Open”:
- “Unverified”: further work needs to be done to decide whether the task - should be completed.
- “In Development”: someone is working on the code and asset changes - necessary to complete the task. This occasionally subsumes preliminary - work, too.
- “In Testing”: code and asset changes are ostensibly complete, - but need testing to validate that the task has been completed - satisfactorially.
-
“Completed”:
- “Development Completed”: work (and possibly testing) has been completed - but the task's results are not yet available to external users.
- “Released”: work has been completed, and external users can see and use - the results.
-
“Abandoned”:
- “Cannot Reproduce”: common in bug/defect tasks, to indicate that the - task doesn't contain enough information to render the bug fixable.
- “Won't Complete”: the task is well-understood and theoretically - completable, but will not be completed.
- “Duplicate”: the task is identical to, or closely related to, some other - task, such that completing either would be equivalent to completing - both.
- “Invalid”: the task isn't relevant, is incompletely described, doesn't - make sense, or is otherwise not appropriate work for the team using the - tracker.
-

None of these are universal.

Transitions show how a task moves from state to state.

Driven by external factors (dev work leads to tasks being marked completed)
- Explicit transitions: “mark this task as completed”
- Implicit transitions: “This commit also completes these tasks”
-
Drive external factors (tasks marked completed are emailed to testers)

States implicitly describe a belief or a desire about the future of the -task, which is a human artifact and may be wrong or overly hopeful. Tasks can -transition to “Completed” or “Abandoned” states when the work hasn't actually -been completed or abandoned, or from “Completed” or “Abandoned” to an “Open” -state to note that the work isn't as done as we thought it was. This is a -feature and trackers that assume every transition is definitely true and -final encourage ugly workarounds like duplicating tickets to reopen them.

Speciation

I mentioned above that bugs are a kind of task. The ways in which bugs are -“different” is interesting:

Good bugs have a well-defined reproduction case - steps you can follow to - demonstrate and test them.
Good bugs have a well-described expected behaviour.
Good bugs have a well-described actual behaviour.

Being able to support this kind of highly detailed speciation of task types -without either bloating the tracker with extension points (JIRA) or -shoehorning all features into every task type (Redmine) is hard, but -necessary.

Supporting structure helps if it leads to more interesting or efficient ways -of using tasks to drive and understand work.

Bugs are not the only “special” kind of task:

“Feature” tasks show up frequently, and speciate on having room for - describing specs and scope.
“Support ticket” tasks show up in a few trackers, and speciate dramatically - as they tend to be tasks describing the work of a single incident rather - than tasks describing the work on some shared aspect, so they tend to pick - up fields for relating tickets to the involved parties. (Arguably, incident - tickets have needs so drastically different that you should use a dedicated - incident-management tool, not a task/bug tracker.)

Other kinds are possible, and you've probably seen them in the wild.

Ideally, speciation happens to support widespread specialized needs. Bug -repro is a good example; every task whose goal is to fix a defect should -include a clear understanding of the defect, both to allow it to be fixed and -to allow it to be tested. Adding specialized data for bugs supports that by -encouraging clearer, more structured descriptions of the defect (with implicit -“fix this” as the task).

Implementation notes

If we reduce task tracking to “record changes to fields and record discussion -comments, on a per task basis,” we can describe the current state of a ticket -using the “most recent” values of each field and the aggregate of all recorded -comments. This can be done ~2 ways:

“Centralized” tracking, where each task has a single, total order of - changes. Changes are mediated through a centralized service.
“Decentralized” tracking, where each task has only a partial order over the - history of changes. Changes are mediated by sharing sets of changes, and by - appending “reconciliation” changes to resolve cases where two incomparable - changes modify the same field/s. The most obvious partial order is a - digraph.

Centralized tracking is a well-solved problem. Decentralized tracking so far -seems to rely heavily on DSCM tools (Git, Mercurial, Fossil) for resolving -conflicts.

The “work offline” aspect of a distributed tracker is less interesting in as -much as task tracking is a communications tool. Certain kinds of changes -should be published and communicated as early as possible so as to avoid -misunderstandings or duplicated work.

Being able to separate the mechanism of how changes to tasks are recorded from -the policy of which library of tasks is “canonical” is potentially useful as -an editorial tool and for progressive publication to wider audiences as work -progresses.

Issue tracking is considerably more amenable to append-only implementations -than SCM is, even if you dislike history-editing SCM workflows. This suggests -that Git is a poor choice of issue-tracking storage backends...

- - - -

- - -comments powered by Disqus -

- - - - - -