JIRA User's Guide

JIRA Setup for ONAP

ONAP defines a number of different projects for the various subsystems.

To view the current set of JIRA projects, go to the Projects menu, select View All Projects from the pull down menu to see what is currently defined.

Below is the current set of Projects; however, note that additional JIRA projects may be added as needs dictate, so this list is not static

Viewing Issues in JIRA

There are many ways to view issues in JIRA. The description here is one way.

Go to Issues menu, select Search for issues

This will bring up the following screen. You will be able to select which Project(s) you want to search, what issue Types (Bug, Epic, Story, Task), what Status and so on. The "More" menu allows you to select additional fields to search on to further narrow down your search.

An alternative to searching, you can use predefined filters provided by JIRA as shown below:

Reporting a Bug

To report a bug against ONAP, select Create (please note that screen display may vary slightly depending from where in JIRA you create the bug)

Assign the bug to yourself if you plan to fix the issue; otherwise, leave Assignee blank

Select Create at bottom of screen

Proposing a New Feature

New feature or enhancement proposals are submitted via JIRA using the Story issue type.

Before you submit your idea, first check to see if something similar already exists in the backlog. If not, go ahead and create a Story.

Searching for a Story in the backlog works the same way as searching for a Bug (Viewing Issues in JIRA), just select Issue Type Story instead of Bug along with the Project(s) of interest in the Search menu. Alternative, you can go to the Backlog board for a particular project, such as shown below for MSO.

To submit your feature or enhancement proposal, go to the Backlog board of the applicable Project and select Create Issue. In our example, we are using MSO.

This will present the following menu, go to the far right and click on the three dots.

This will bring up the Create Issue screen as show below.

Provide a clear and concise Summary of the new feature

Provide detailed Description of the new feature

Select Create

JIRA Issue Types

There are generally 5 Jira issue types used within ONAP; the 5th one, Sub-task, can only created from within a Story.

Epic

An Epic is used when a feature is large in scale, may take several sprints to complete, and/or may spans multiple components.

The Epic itself is an umbrella issue. An Epic is comprised of one or more stories.

Usage: Anyone can create an Epic and put it in the backlog for a project, but is usually created by PTLs

Story

A Story or user story is a piece of work that can be completed within a sprint. It is usually part of an Epic.

Usage: Anyone can create a Story and put it the backlog for a project.

Bug

A Bug is a defect, an error, or a flaw that requires a fix, it can be a code change, a documentation update, configuration change, etc…

Usage: Anyone can create a bug and assign to himself or someone else or leave it unassigned if they wish someone else to pick it up and work on it

Task

Task can be used to breakdown a story into smaller work units that can be completed in a day or two; however, for deconstruction of a story, it is recommended that a Sub-task be used. Using a Sub-task will save the user Jira steps and will be automatically linked to the story since it's created from within the story. See Sub-task below.

Tasks can be used to track discrete activities that must be done and may not necessarily be related to a story (for example, fix a Jenkins job); however, if a user chooses to use Task issue type to track work associated with a story, be sure to link the Task to the Story via the Linked Issues and Issue fields as illustrated below.

Sub-task is used to breakdown a story into smaller work units that can be completed in a day or two. Breaking a story down into discrete work units that can be burned down daily will communicate progress on the story.

Sub-tasks are created from within the story via the More menu option by selecting Create sub-task

JIRA Workflow

The ONAP projects have all aligned on the following workflow, which is a slightly modified Atlassian Classic workflow.

JIRA Statuses and supported transitions

From Status

Transition

To Status

a

Open

Start Progress

→

In Progress

b

Open

Deliver

→

Delivered

c

Open

Close

→

Closed

d

In Progress

Stop Progress

→

Open

e

In Progress

Submit

→

Submitted

f

In Progress

Close

→

Closed

g

Submitted

Deliver

→

Delivered

h

Submitted

In-Progress

→

In Progress

i

Delivered

Close

→

Closed

j

Delivered

Reopen

→

Reopened

k

Reopened

Close

→

Closed

l

Reopened

Start Progress

→

In-Progress

m

Reopened

Deliver

→

Delivered

n

Closed

Reopen

→

Reopened

JIRA Resolution Code

The Resolution field is very important because combined with Status field, it conveys critical information to the community about the general disposition of the Jira issue.

The below list is the set of Resolution options provided as defaults by Jira. Some projects have added to this list, such as Not A Bug, PTLs can request LF to add more Resolution options to their project; however, recommendation is that one set be defined that is used across all projects - this is a work in progress still.

Unresolved (by default)

Done: Issue is fixed, closed

Cannot Reproduce (self explicit)

Duplicate: Provide duplicate issue number

Won’t Do: Explain reasons why the issue will never be fixed

JIRA Version

Affects Version/s: Project version(s) for which the issue is (or was) manifesting - this field is really used for Bugs, think of it as the "Found In" version of the software.

Fix Version/s: Project version(s) for which the issue is (or was) fixed or a story is delivered.

JIRA Priority Definition for Bugs

Use this guideline to setup the mandatory "JIRA Priority" field. Note that the PTL has jurisdiction over this criteria and may thus requalifies the priority.

Highest: Catastrophic defect that causes total failure of the software or unrecoverable data loss with no available workaround. Complete shut-down of the process, nothing can proceed further. Blocks testing of the product / feature.

Must be fixed in the next build.

High: Severely impaired functionality. Erratic performance and reduced system availability. It may cause major components or features of the system to be unavailable although certain parts of the system remain functional. A workaround may exist but its use is unsatisfactory or at a high time cost (manual intervention required).

Must be fixed in any of the upcoming builds and should be included in the current release.

Medium: Failure of non-critical aspects of the system but results in an inconvenient situation. It causes some undesirable behavior, but the system is still functional. There is a reasonably satisfactory workaround. It is still a valid defect that should be corrected

May be fixed after the release or in the next release.

Low: It won't cause any major break-down of the system. It does not result in the termination of services, does not impact usability of the system and the desired results can be easily obtained by a workaround.

Fix can be deferred until after more serious defect have been fixed.

Lowest: No impact to the functionality. More related to the enhancement of the system.

May or may not be fixed at all

Recommendations for writing Proper JIRA Bug Issue

Do and Don't

1 record per Jira Issue. Do not report multiple bugs within one single JIRA Issue.

Otherwise, it makes it very difficult:

to have a focused discussion

to track progress

Even if you encountered several issues at once, you should open a separate JIra Issue for each and Link issues together.

Keep ongoing communication in JIRA. Email do not scale. Email are lost. Use JIRA to provide all necessary Logs, code sniptets, screenshots.

In case you need to get notified on a change: Use JIRA Watch capability.

Assignee: By default, while creating a JIRA Issue, the PTL is assigned. Issue can be re-assigned by anyone. (we need to discuss best practice for assigning issues and come to consensus)

Even if status is Closed, issue can be re-opened. Nothing is preventing to re-open a closed JIRA Issue.

The JIRA Issue Summary should precisely describe the problem. "X is broken" is not a helpful description. "X is doing Y instead of Z" is much better.

Description Field

Provide more details on the issue

Describe the error you see, and describe the behavior expected

Provide steps to reproduce the error

If possible, provide actual commands to run

Attach logs or screenshots

Try to reduce the problem to the smallest possible use case to make it easier to reproduce the bug and to test the solution

5 Comments

Based on Randa's feedback, I would like to share with you what is currently implemented on LF ONAP JIRA (http://jira.onap.org/)

Jira Issue Types

There are 4 Jira issue types that are accessed via the Create menu; there is a 5th that is access from within a Story.

Epic

An Epic is used when a feature is large in scale and/or spans multiple components, and may require one or more sprints to complete. An Epic is comprised of one or more stories.

Usage: Anyone can create an Epic and put it in the backlog for a project

Story

A Story or user story is a piece of work that can be completed within a sprint. It is usually part of an Epic.

Usage: Anyone can create a Story and put it the backlog for a project

Bug

A Bug is a defect, an error, or a flaw that requires a fix, it can be a code change, a documentation update, configuration change, etc…

Usage: Anyone can create a bug and assign to himself or someone else or leave it unassigned

Task

Task can be used to breakdown a story into smaller work units that can be completed in a day or two; however, for deconstruction of a story, it is recommended that a Sub-task be used. Using a Sub-task will save the user Jira steps and will be automatically linked to the story since it's created from within the story. See Sub-task below.

Tasks can be used to track discrete activities that must be done and may not necessarily be related to a story; however, if a user chooses to use Task issue type to track work associated with a story, be sure to link the Task to the Story via the Linked Issues and Issue fields as illustrated below.

The 5th Jira issue type is created from within a Story using the More menu option:

Sub-task

Sub-task is used to breakdown a story into smaller work units that can be completed in a day or two. Breaking a story down into discrete work units that can be burned down daily will communicate progress on the story.

Sub-tasks are created from within the story via the More menu option and selecting Create sub-task

Jira Status Transitions/Workflow

ONAP Jira supports the following workflow. It is a slight derivation of the Classic Atlassian workflow.

The table below provides tabular representation of the various Status transitions supported with some helpful notes on when the transition may apply.

From Status

Transition

To Status

Notes

a

Open

Start Progress

→

In Progress

Issue is assigned and work has started on the issue

b

Open

Resolve Issue

→

Delivered

Use case example: Question posed/question answered issue, no code:

Resolution field set to Done.

c

Open

Close Issue

→

Closed

Use case example: issue rejected, Resolution field set to Rejected

d

In Progress

Stop Progress

→

Open

Use case example: issue postponed.

Resolution field set back to Unresolved, if applicable

e

In Progress

Submit

→

Submitted

Use case example: code submitted to Gerrit, but not yet approved for merge.

Resolution field stays Unresolved at this stage until Gerrit approval is completed.

f

In Progress

Close Issue

→

Closed

Use case example: Use for Sub-tasks, which use a simpler workflow: Open/In Progress/Closed

g

Submitted

Deliver

→

Delivered

Use case example: Code submission approved, merged.

Resolution field set to Implemented or Done for Story, Fixed for Bug.

h

Submitted

In-Progress

→

In Progress

Use case example: code submission failed, needs to be reworked

Resolution field should be Failed or Unresolved

i

Delivered

Close Issue

→

Closed

Use case example: The work is complete, issue can be closed.

Resolution field should not be Unresolved when an issue is closed.

j

Delivered

Re-Open Issue

→

Reopened

k

Reopened

Close Issue

→

Closed

l

Reopened

Start progress

→

In-Progress

m

Reopened

Resolve issue

→

Delivered

n

Closed

Re-Open Issue

→

Reopened

Jira Resolution Field

The Resolution field is very important because combined with Status field, it conveys critical information to the community about the general disposition of the Jira issue.

The following Resolution values are provided:

Resolution

Meaning

Unresolved

Default Resolution while issue is being worked/In-Progress

Cannot Reproduce

Used for reported bugs that cannot be reproduce

Defer

Issue is Deferred for another sprint or release

Done

Use for Stories when completed or when responding to questions submitted via Jira.

Duplicate

Used when duplicate issues tickets are created. When duplicate issues exist; one should be Closed with Duplicate Resolution and linked to the original ticket or a comment should be added point back to the original ticket.

Failed

Used when a fix fails or Code submission fails Gerrit checks.

Implemented

Used for Stories when completed

Not a Bug

Used when a reported Bug is not really a bug, could be an environment issue or misconfiguration, for example.

Rejected

Used when a story submission is not accepted by the TSC

Test

Used within the sprint team when developer wants to request tester as part of scrum team to test the story.

Won't Do

This is provided as a default by Jira; this can be used instead of Rejected for Story, or for cases of Bugs that are not planned to be fixed due to the very low priority nature.

Works as Designed

Used for issues that are reported as Bugs, but code is actually working as intended

Fixed

Used for Bugs when a fix is delivered.

Won't Fix

Similar to Won't Do

Incomplete

This is provided as a default by Jira. Don't have a strong use case for it yet.

Jira Best Practices

Bugs <this can probably be placed under section on Reporting a Bug"

One issue per Jira ticket. Do not report multiple bugs within one single JIRA Issue. Otherwise, it makes it very difficult:

to have a focused discussion

to track progress

Even if you encountered several issues at once, you should open a separate JIra Issue for each and Link issues together.

Keep ongoing communication in JIRA. Email does not scale. Emails are lost. Use JIRA to provide all necessary Logs, code snippets, screenshots.

The JIRA Issue Summary should be precise and informative about the issue it is reporting: "X is broken" is not a helpful description. "X is doing Y instead of Z" is much better.

Provide more details on the issue in the Description field

Describe the error you see, and describe the behavior expected

Provide steps to reproduce the error

If possible, provide actual commands to run

Attach logs or screenshots

Try to reduce the problem to the smallest possible use case to make it easier to reproduce the bug and to test the solution

Thanks for your feedback. I initially added in this page the definition of the Jira issue type, transitions and resolution types as they were not existing. I think the definition you have provided for JIRA Issue Type complements very well and can be merged together.

Regarding the workflow, I would like to proposed a few simplification by removing the "Submitted" and "Delivered" status who are related to submission into Gerrit. I am afraid developers won't take the time to update JIRA to reflect these 2 statuses. Furthermore, as there is a linkage between JIRA and Gerrit, from any JIRA ticket we can learn in Gerrit Status.

I would also remove "Reopened" status and update the use case by suing "ToDo" (open) status. JIRA history can tell us if a ticket has been re-open or not.

As far as the list of resolution field, I would like to propose to simplify. I think there are redondances:

1) Fixed- Done

2) Rejected-Won't Do-Won't Fix

3) Defer: use "Fix version" field to designate which release this will be addressed

4) Failed: if a fix fails, I would simply recommend to change the status to "ToDo" and for the person who tested to explain why it failed.

5) Implemented: Instead of this being a resolution, I would recommend to make it a status (this will help to know reported need to verify the fix)

6) Test: Not sure this is required. We could use status Implemented.

7) Incomplete: yes, we don't need this and ask LF to delete this resolution field.

I think though we should coordinate and work with the community to get their feedback as well.

The workflow provides sufficient flexibility if a team chooses not to utilize the Submitted and Delivered State. They can use Open -> In-Progress -> Closed. Teams can have craft their own working agreements as part of the project kickoff.

But If the workflow is simplified to "Open -> In-Progress -> Closed" then

1) how the reporter knows that he/she can review what has been done before he decides to close the JIRA item

2) how the testing team knows that the code is delivered so they can start to test it.

Regarding the Resolution, it is true that we are not obliged to follow the Agile terminology.

Please find additional comments:

1) Fixed- Done - a Story is Done, a Bug is Fixed but we are not obliged to follow the Agile terminology.

2) Rejected-Won't Do-Won't Fix

Won’t Do is a Jira default, but I can see a case for getting rid of it and just using Rejected,

A story is Won’t Do or Rejected. So we could get rid of Won’t Do.

A bug is Won’t Fix

3) Defer: use "Fix version" field to designate which release this will be addressed

it just gives the team an option to better managing their work.

4) Failed: if a fix fails, I would simply recommend to change the status to "ToDo" and for the person who tested to explain why it failed.

This was requested by one of the teams.

5) Implemented: Instead of this being a resolution, I would recommend to make it a status (this will help to know reported need to verify the fix)

We can use Implemented or Done resolution for Stories, So we could simplify the list is that way,

6) Test: Not sure this is required. We could use status Implemented.

This was requested by one of the teams.

7) Incomplete: yes, we don't need this and we ask LF to delete this resolution field.

We need to clean up this page to make it more usable and less confusing for folks. When ONAP was initially open sourced, the projects were using (and continue to use) the flow described in the comment above by Catherine. Later on, new projects introduced, mainly ones from the Open-O merge started using the flow you describe. Since it's a per project decision on what is used, it sounds like both need to be supported. Can we work together to clean this page up? Thanks, Randa