Issue tracking

One shared list of every bug and piece of work, each with a status, an owner and a priority, so nothing lives only in someone’s head or inbox.

How it works

A ticket (also called an issue, or a work item in today’s Jira) is a record of one bug, feature or task. It has a title and description, who reported it, who owns it now, a priority, labels and a status. The statuses form a workflow: the simplest is To do, In progress, Done, and Jira describes a workflow as statuses plus the transitions allowed between them, with a resolution such as Done, Won’t Do or Duplicate when the item closes. Work nobody has started waits in a backlog, ordered by priority, and the team pulls from the top into a sprint or onto a kanban board. Every comment and status change is kept, so months later the ticket explains why something was built. Trackers also link to code: put Fixes #482 in a commit message or pull request description, and GitHub or GitLab closes issue 482 when that change reaches the default branch. Jira, Linear, GitHub Issues, GitLab Issues, JetBrains YouTrack and Azure Boards (part of Azure DevOps) all follow this model.

Think of it as

The ticket rail in a restaurant kitchen. Each order is its own slip that moves from received to cooking to served. Nobody has to remember orders, and one glance shows which table has waited too long.

Reach for it when

More than one person works on the same product and needs to know who is doing what
Bugs reported by users or support have to reach an engineer and not get lost
You want to find out later why a change was made, by linking tickets to commits and pull requests
Planning a sprint, a release or a roadmap from a ranked backlog

Think twice when

Filing every passing idea until the backlog holds thousands of stale tickets nobody reads
Replacing a five-minute conversation with a ticket that bounces between people for days
Counting closed tickets as a measure of how good someone is: people will split and game tickets

A real example

A customer tells support that CSV export fails. Support opens issue #482 with the steps to reproduce (open Reports, choose Export, pick March), what they expected (a file download) and what they saw (an error 500), sets the priority to High and links the customer’s conversation. An engineer assigns it to herself, moves it to In progress and finds that names with commas break the export. Her pull request says Fixes #482; when it merges into main, GitHub closes the issue, and support tells the customer the fix is live.

Ticket hygiene#

A tracker is only as useful as its tickets. Joel Spolsky’s 2000 essay “Painless Bug Tracking” set out rules that still hold.

Steps, expected, actual

every bug

Every good bug report needs three things: the steps to reproduce, what you expected to see, and what you saw instead. Without the expected result, a reader may not see why it’s a bug at all. Cut the steps down to the fewest that still reproduce it.

One owner at a time

assignee

A ticket is assigned to exactly one person, who either works on it or hands it on. In Spolsky’s workflow a resolved bug goes back to the person who opened it, who confirms the fix before it is closed.

One problem per ticket

scope

A ticket that holds three bugs can never be closed cleanly. Split it, and mark repeats as duplicates of the original so the history stays in one place.

Prune the backlog

monthly

Old tickets that nobody will do hide the ones that matter. Close them with a short reason (Won’t Do is a resolution, not a failure); a real problem will be reported again.

Common trackers#

	Since	Where it lives	Notable
Bugzilla	1998	Self-hosted, free and open source	Written for mozilla.org to replace Netscape’s in-house tracker; strong workflow and security controls
Jira	2002	Atlassian cloud or Data Center	Configurable workflows, issue types and boards for Scrum and kanban; now calls tickets work items
GitHub Issues	2009	Next to the code on GitHub	Labels, Projects boards, and issues closed from commits and pull requests
GitLab Issues	n/a	Next to the code on GitLab	Closing patterns in commits and merge requests; Service Desk turns customer emails into tickets
Linear	2019	Cloud	Per-team workflows and cycles of 1 to 8 weeks that roll unfinished issues over
Azure Boards	n/a	Azure DevOps	Work items, backlogs and boards for agile teams in Microsoft’s toolchain

In code · bash

# A closing keyword links the commit to the issue;
# GitHub and GitLab close #482 when this reaches the default branch.
git commit -m "Quote fields that contain commas in CSV export" -m "Fixes #482"

# Other forms GitHub accepts:
#   Closes #10   Resolves #10   Fixes octo-org/octo-repo#100

Often confused with

Sprints Customer support Error tracking Version control

Where it came from1998–2015

Software teams once tracked bugs in spreadsheets, email threads and notebooks. When mozilla.org came online in 1998, one of its first products was Bugzilla: Terry Weissman wrote it in Tcl to replace the in-house system Netscape had used, put it on a public server on April 6, 1998, and released it as open source that August, by then ported to Perl. Anyone on the internet could now file a bug against a browser and watch it get fixed, and a large number of projects, commercial and free, adopted it.

In November 2000 Joel Spolsky’s essay “Painless Bug Tracking” turned the practice into rules: steps to reproduce, expected and actual results, one owner at a time, and only the person who opened a bug can close it. In 2002 Atlassian launched Jira, a commercial tracker that went from bugs to all kinds of work and became the default in many companies.

The next change put tickets next to the code. In April 2009 GitHub added an issue tracker to every repository, with labels and the ability to close issues from commit messages. GitLab does the same with closing patterns, and newer tools such as Linear built cycles, triage and keyboard-first speed into the tracker itself.

Why it’s built this way

A ticket has one owner and a status: Bugs that everyone knows about but nobody owns don’t get fixed. Assigning each ticket to one person and showing its state makes dropped work visible.
Expected versus actual in every report: A report that only says what happened leaves the reader guessing whether it’s a bug or a misunderstanding of the spec. Stating the expected result settles that.
Close tickets from commits: Developers forget to update the tracker after merging. A keyword such as Fixes #10 in the commit links the change to the ticket and closes it automatically, so the record matches the code.
Configurable workflows: A two-person team needs To do, In progress and Done; a regulated company may need review and sign-off states. Jira and its successors let each team define its own statuses and transitions.

Timeline

1998
Bugzilla goes live at mozilla.org in April and is open-sourced in August
2000
Joel Spolsky publishes “Painless Bug Tracking”
2002
Atlassian launches Jira
2009
GitHub adds Issues, with closing from commit messages
2015
Atlassian splits out Jira Software for software teams

Sources14

Improve this page on GitHub