Jira Usage Help

From Zephyr Project Wiki
Jump to: navigation, search

The purpose of this page is to help Zephyr Project Jira users understand the differences between Epics, Stories, Tasks, Bugs, and Subtasks so they know when to create each and how to properly related them to one another.

Jira Issue Type Descriptions


  • The smallest unit of feature-development work that is planned and tracked to deliver an increment of functionality to the product. Generally, the granularity of a story is days to a few weeks to complete.
  • Typically written using the following format:
  • “As a <type_of_user>, I want <goal> so that I <receive_benefit>.”
  • Must always include specific and measurable acceptance criteria.
  • Large stories (with granularity of more than a few weeks to complete) should be split into smaller stories.
  • May or may not be associated with an epic. Some stories are self-contained one-offs.


  • Something which is not a story, but is nontrivial and needs to be completed. It’s not implementation of a feature in the product. It’s generally something that does not: (1) involve writing/changing code to implement a new or changed feature, and (2) performing the necessary testing associated with (1).
  • Generally, the granularity of a task is days to a few weeks to complete.
  • Because code-related states are not applicable, tasks have a simpler workflow.
  • Because tasks take developers’ time they are tracked in efforts to better understand resource availability and loading.
  • May or may not be associated with an epic.
  • Good examples of a task would be:
    • Planning-related work (e.g. design work needed before being able to specify, scope, or estimate the size of a story)
    • Research work needed for an upcoming feature
    • Proof-of-Concept work where the code created for the POC is not yet part of the product.
      • Note: Adding the features/functionality demonstrated by a POC to the product would be done within the context of a story.
    • Architectural Study


  • A reported problem with already-released functionality. In other words, something broken in a released version of the project (like v1.5.0), OR
  • A reported problem with already-merged, but not yet released, functionality. In other words, something that’s already been implemented, merged, and tested to meet acceptance criteria, but then is later found to be broken before it is released in a version of the product (like a v1.x.0 which is in-progress of being developed).
  • May or may not be associated with an epic.


  • Significantly larger bodies of work than Stories, Tasks, or Bugs. For example, an epic may take a few months to complete.
  • A body of work that is almost always delivered over a set of sprints or releases during which its scope may be modified as the team learns more about the Epic through development and customer feedback.
  • Work that is comprised of many Stories, Tasks, and/or Bugs. Due to its large scope, epics must always be “split up” into smaller stories, tasks, or bugs to incrementally deliver desired results.
  • Epics are used to group together related work (Stories, Tasks, and/or Bugs).


  • Smaller work items of a story, task, or bug.
  • Always associated with a story, task, or bug.
  • Sub-tasks themselves are not planned and tracked like stories, tasks, and bugs are.
  • Sub-tasks are available for use by developers to keep themselves organized by specifying and tracking their lower-level work.
  • Generally, the granularity of a subtask is hours or days to complete.

Hierarchy of and Relationships Between the Different Issue Types

The hierarchy diagram shown below is not meant to show every possible relationship between Epics, Stories, Tasks, and Bugs that can be created using Jira’s link feature (accessible via the More→Link button when viewing an issue).

Zephyr Jira Issue Type Hiearchy

  • An Epic may have Stories, Tasks, and/or Bugs associated with it. Bugs are less likely to be associated with an Epic, but it is possible if some bug fixing is relevant to an Epic and it’s desired that the set of bugs get tracked with the Epic.
  • A Story, Task, or Bug can only be associated with one and only one Epic, but may not be associated with any Epic at all.
  • Subtasks are optionally used to identify lower-level work associated with Stories, Tasks, or Bugs.
  • Subtasks cannot be directly associated to Epics.
  • Subtasks cannot be created standalone; they must be associated with higher-level Stories, Tasks, or Bugs.

Real Examples in Jira

To see real examples of the relationships and hierarchy, open this Jira board (https://jira.zephyrproject.org/secure/RapidBoard.jspa?rapidView=18&view=planning.nodetail), then open the EPICS panel by clicking on the 'Show epics panel' link to the left of the issues list.

Jira backlog screen pointing out the EPICS panel

With the EPICS panel open Jira shows the Epic associated with each issue in the Backlog. See the arrows on the right below. On the left, in the red box, is the list of Epics associated with all of the issues in the Backlog. By clicking on an Epic in the EPICS panel on the left, the list of issues associated with the Epic is shown in the Backlog panel on the right. Open an issue to find subtasks, where they are being used. Not all issues have subtasks.

Jira backlog screen pointing out Epics