Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 29 ยท Jira Basics

Issues, Issue Types and Workflows

Learn what a Jira issue is: epics, stories, tasks, bugs and subtasks, key fields, priorities, statuses, transitions, links and labels, with runnable models.

Everything in Jira is an issue. A feature to build, a bug to fix, a question to answer, a chore to finish: each one is an issue with a key such as SHOP-142, a summary, a description and a handful of fields. The word "issue" sounds negative, but it simply means "a unit of work that someone can track". If you understand issues, you understand 80% of Jira.

This lesson covers the issue types and how they nest, the fields you will fill in every day, how a workflow moves an issue from "not started" to "done", and how links and labels connect issues. The real Jira cannot run on this site (it is a hosted product with accounts), so its screens and settings are described in words and read-only blocks. The runnable examples are stand-ins: small JavaScript models that follow the same rules, so you can see how the ideas work. They are not Jira's code.

One issue, many shapes

Epic A big goal made of many issues.
Story Value for a user.
Bug Something that is broken.
Task Work that is not a user story.

A subtask splits one issue into smaller steps.

1 / 2

Issue types

Jira projects ship with a small set of issue types. The names can be changed by an administrator, but the standard software set looks like this:

Type Use it for Example
Epic A large body of work that takes several sprints "Customer accounts"
Story A feature described from the user's point of view "As a shopper, I can reset my password"
Task Work that has to be done but is not a user-facing feature "Upgrade the database server"
Bug A defect: the product does not behave as intended "Cart total ignores discount codes"
Subtask A step inside another issue "Write the reset-email template"

If you have not yet written stories, read User Stories and Acceptance Criteria first: a story is the most common issue type on a Scrum team, and the quality of its text decides how useful the Jira issue is.

The hierarchy

Issue types form levels. In the classic layout, an epic sits at the top, stories, tasks and bugs sit in the middle, and subtasks sit at the bottom. An epic groups its children (Jira calls the link "parent"), and a subtask always belongs to exactly one parent issue. Subtasks cannot have children of their own, and a subtask cannot live alone.

flowchart TD
  E["Epic: Customer accounts"] --> S1["Story: Register"]
  E --> S2["Story: Reset password"]
  E --> B1["Bug: Login fails on Safari"]
  S2 --> T1["Subtask: Email template"]
  S2 --> T2["Subtask: Token expiry"]

Epic at the top, work items in the middle, subtasks at the bottom.

A good rule of thumb: if the work fits in one sprint and one person can own it, it is a story, task or bug. If it needs several sprints, it is an epic. If it is a step that nobody would demo on its own, it is a subtask.

Jira Cloud also lets administrators add levels above epics (for example "Initiative") in some plans, and team-managed projects call the hierarchy "child work items". The names change between versions and plans, so check your own project's settings when something looks different.

The fields you will use every day

An issue is a bag of fields. Some are required, some are optional, and administrators can add their own (see Workflows, Permissions and Customization).

  • Summary: one line that names the work. Keep it short and specific: "Reset-password email is not sent" beats "Email problem".
  • Description: the details. For a story, the user-story sentence and the acceptance criteria. For a bug, the steps to reproduce, the expected result and the actual result.
  • Assignee and Reporter: who is doing the work and who raised it.
  • Priority: how urgent it is. The default scale is Highest, High, Medium, Low, Lowest.
  • Status: where the issue is in its workflow (next section).
  • Labels: free-form tags without spaces, like checkout or needs-design.
  • Components: parts of the product, defined per project, for example "Payments".
  • Story point estimate and Sprint: used in Scrum projects, see Estimating with Story Points and Boards, Backlogs and Sprints in Jira.
  • Fix versions and Affects versions: the release that will contain the work, or the release where a bug was seen.

Priority and sprint are different things. Priority says how important an issue is in general; the sprint says when the team plans to do it. A "Low" priority bug can still be in this sprint because it is a quick fix.

Writing a good bug

A bug is only useful if someone else can reproduce it. A template that works in almost every team:

TEXT
Summary:  Discount code is ignored when the cart has a gift card
Steps:    1. Add any product and a 25 USD gift card
          2. Enter the code SPRING10 at checkout
Expected: Total drops by 10% of the product price
Actual:   Total does not change; no error is shown
Notes:    Happens in Firefox and Chrome; started after release 4.2

Statuses, transitions and the workflow

A status is a named stage ("In Review"). A transition is the allowed move from one status to another. Together, the statuses and transitions of an issue type form its workflow. The simplest software workflow has three statuses: To Do, In Progress, Done. Most teams add "In Review" or "Testing".

Every status belongs to one of three status categories: To Do, In Progress or Done. Boards and reports use the category, not the name. That is how Jira knows an issue in "Shipped" counts as finished even though no one named it "Done".

A workflow is just a state machine. The stand-in below enforces the moves and keeps a history, the way Jira's issue history does. The transitions below are an example, not Jira's built-in defaults.

JS A workflow as a state machine

Press Run (or Ctrl + Enter) to see the console output here.

No output.

In real Jira, a transition can also have conditions (who may use it), validators (checks before it runs) and post functions (things that happen after it). Those belong to administration, covered in Workflows, Permissions and Customization.

Keep workflows short. Every extra status is another column to maintain and another hand-off to wait in. If two statuses mean the same thing in practice, merge them.

Epics, children and roll-ups

Epics are useful because you can ask "how far along is the epic?" The answer is computed from the children: how many are in the Done category compared with the total. Real Jira shows this as a progress bar. The stand-in below builds a small hierarchy and prints it as a tree with a roll-up.

JS An issue tree with a progress roll-up

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that the roll-up counts only the leaves (issues without children). Counting both a story and its subtasks would count the same work twice.

Linking issues and using labels

Hierarchy answers "what is this part of?". Links answer "how does this relate to that?". Common link types are:

  • blocks / is blocked by: SHOP-9 cannot start until SHOP-8 is done.
  • duplicates / is duplicated by: two reports of the same problem. Close one and link it to the other.
  • relates to: a loose connection that you want someone to find later.
  • clones / is cloned by: a copy of an issue, for example for another team.

Use "blocks" sparingly; a board full of blocked-by links is a sign that the team has dependencies to remove, not just track. Labels are lighter than links: they have no structure at all, so keep a short list of agreed labels, otherwise you end up with Checkout, checkout and check-out side by side. For anything you filter by often, prefer a component, a version or a custom field, which administrators can control. Searching by any of these fields is the subject of JQL and Filters.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which description fits a subtask?

    A subtask always belongs to exactly one parent issue. Epics are the large goals, and bugs are defects.
  2. 2. A board column is named "Shipped". How does Jira know these issues are finished?

    Boards and reports use status categories (To Do, In Progress, Done), not the status names.
  3. 3. Why does the epic roll-up in the stand-in count only issues that have no children?

    The leaves are the actual units of work. Adding their parents would double count.
  4. 4. What is the main difference between priority and sprint?

    A low-priority quick fix can still be planned in the current sprint.

Summary

  • Everything in Jira is an issue with a key, a summary, a description and fields.
  • Epics group stories, tasks and bugs; subtasks split one issue into steps and always have a parent.
  • A workflow is a set of statuses and allowed transitions, a state machine; status categories (To Do, In Progress, Done) drive boards and reports.
  • Priority says how important, sprint says when; labels are free-form, components and versions are controlled.
  • Links like "blocks" and "duplicates" connect issues across the hierarchy.
  • The JavaScript examples are stand-ins for the rules; real Jira runs only on Atlassian's cloud.

Next, put issues on a board and plan a sprint: Boards, Backlogs and Sprints in Jira.