We've migrated material from this wiki to the documentation site or to the new Zephyr GitHub wiki

Jira Usage Help

From Zephyr Project Wiki
Jump to: navigation, search

The purpose of this page is to help the community of Zephyr Project users and developers to understand how the Zephyr Project intends Jira to be used.

Zephyr Project's Jiras

The Zephyr Project uses three different Jira databases which are accessible from the Zephyr System Dashboard.

You can also go directly to each Jira project by following these links:

When creating or looking for issues, be sure you're using the correct Jira project.

Jira Issue Type Descriptions

The information below describing the differences between Epics, Stories, Tasks, Bugs, and Subtasks is provided so users can understand when to create each and how to properly relate them to one another. The reason the Zephyr Project uses different issue types is because the work required for each is different and this results in different workflows (i.e. statuses) needed for them. For instance, Stories and Bugs result in code changes so the work to get them completed requires code reviews and merging of code. Tasks are simply work that needs to be done that does not require code changes. Because of that it makes no sense to have use code review and merge statuses for tasks. The same is true of epics because epics are simply a collection of stories, tasks, and/or bugs. Therefore, an epic uses the same statuses as tasks. The information below explains the differences between the different issue types and hopefully you can understand why they are needed.


  • 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 is NOT implementation of a feature in the product; that should be captured as a story. 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).
  • If the work to be done requires writing/changing code of the product, it must be captured as a story, not a task.
  • 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).


  • The use of subtasks is completely optional. They are available simply to specify lower level detail of a story, task, or bug, if it's needed.
  • 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 (, 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

Priority Definitions

The meanings of the three different priority levels are as follows:

Priority Level When used in Stories and Tasks When used in Bugs
High Must-Have in planned release Must be fixed in the next release
Medium Should-Have in planned release Should be fixed in the next release
Low Nice-to-Have in planned release Nice to be fixed in the next release
Undecided Priority has not been decided

Jira Workflow Status Definitions

The meanings of the different statuses are as follows:

Note: In some cases the statuses have slightly different meanings depending on the issue type and some of the statuses are not used for some issue types.

Status When used with Stories When used with Bugs When used with Tasks When used with Epics
New In planning or in the queue to be planned later A new bug that's not yet triaged In planning or in the queue to be planned later In planning or in the queue to be planned later
To Do Properly formed story (with acceptance criteria) that's prioritized and assigned to a developer Triaged, prioritized, and assigned to a developer for fixing Prioritized and assigned to be completed Prioritized and assigned with stories, tasks, and/or bugs associated to it
In Progress In the process of being implemented and unit tested In the process of determining root-cause and fixing In the process of being completed In the process of implementing/completing/fixing the stories/tasks/bugs associated with it
Code Review Implemented, unit tested, and code changes are being reviewed Fix determined and required code changes are being reviewed N/A N/A
Merged Code is merged and awaiting verification Fix is merged and awaiting verification N/A N/A
Closed Verified to meet acceptance criteria Verified to be fixed Completed All associated stories, tasks, and/or bugs are completed