Introduction

This document describes documenting requirements and use cases, as well as integration testing, using Jira.

UPDATE May 1, 2020

After using the requirements JIRA for the Frankfurt release, I've made some changes to improve the process, which we will begin using with the Guilin release:

1. Removed sub-tasks for TSC milestone approvals.  Now these are custom fields within the epic.
   1. This also simplifies the cloning process, since users no longer need to clone the subtasks, which created some confusion in Frankfurt.
2. Added fields for: 
   1. Requirement or Use Case
   2. Proof of Concept (PoC)
   3. t-shirt size,
   4. milestone scorecards,
   5. milestone TSC approvals,
   6. arch subcommittee review status (not yet performed, not required, GO, NO GO)
   7. scope status (original scope, reduced scope, de-scoped)
3. Added a template in the description to capture:
   1. basic description of use case or requirement

   2. Link to HLD/LLD

   3. Dependency Relationships with Other Projects

   4. Project Impact

   5. Support Status for each Affected Project 

   6. Integration Leads

   7. Company Engagement

4. ALL data contained in the release requirements table is now captured in the JIRA issue

Process

Requirements and Use Case Creation

1. Navigate to  REQ-1 - Getting issue details... STATUS
2. Select More==>Clone++
3. Clone the issue in the same project (i.e., REQ).
4. Modify the "epic name" and "summary" fields for your requirement. These may be the same, if you wish.
5. Click the "Create" button.
6. Click the "Edit" button.
7. The "fixVersion" field should already be set, but if not, set it to the release for which the requirement is intended (e.g. "Guilin Release")
8. Set the following fields, if known.  Note: If not known, or not yet determined, wait until the information is known to set the field.
   1. Assignee - this should be one of the requirements owners, if more than one.  Use the template in the description field to document all of the requirements owners.
   2. Requirement or Use Case (defaults to "Requirement)
   3. PoC - check this box if the requirement or use case is a Proof of Concept (PoC)
   4. TSC priority (0 - 4).  Note:  this field is set by the TSC.  Please do not change the field unless you have received direction from the TSC.
   5. Architectural Review Status (defaults to "not yet done") 
      1. Note:  architectural review status is determined by the arch subcommittee.  Do not set this field until you get feedback from the subcommittee.
      2. Upon completing arch review, please link the ONAPARC JIRA as a blocking issue ("is blocked by") for the REQ JIRA.
   6. T-Shirt Size (defaults to M)
9. If it has not yet been done, fill in the template contained in the "description" field.
10. You may do this now, or later:  Create a "story" issue in a project or committee JIRA project and link it to the requirement issue by setting the "linked issues" field to "blocked by" in the requirements issue.
    1. All of your technical issues related to the requirement should be linked to the story.
11. Click "Update".

Requirement and Use Case Updates at Release Milestones

Note:  the fields mentioned below are not initially visible in JIRA unless in edit mode. Once the field is set, it will appear on the form after it is updated.

Note:  Each update to the requirement should be accompanied by a comment that explains the update, as well as any clarifying information about status.

1. By M1, all of the fields mentioned above under "Issue Creation" should be known and entered in the issue.  If not, the requirement should not be approved for M1.
2. Enter the scorecard for the milestone as well as a comment that explains the scorecard and the current status.  A scorecard without an accompanying comment is not acceptable.
3. The release manager or the TSC chair will enter the TSC decision on approval of the requirement for the milestone.  
   1. If the TSC has questions about the status of the requirement, then a question will be entered as a comment to the issue.  The requirement owner must respond to the question by adding another comment to the issue.
4. If the requirement is reduced in scope, or de-scoped, then update the "Scope status" field (defaults to "Original scope").
5. If the requirement is changed to a Proof of Concept (PoC), then check the "PoC" box.
6. Once the requirement is either completed, or de-scoped, then mark the issue "Closed".  Add a comment explaining why the issue is being closed.

Integration Test Task Creation

Beginning with the Guilin release, we will replace the integration test status table with a an embedded Jira table, similar to what was done with requirements and use cases.

1. Navigate to  REQ-421 - Getting issue details... STATUS
2. Select More==>Clone++
3. Clone the issue in the same project (i.e., REQ).
4. Modify the "summary" field.
5. Click the "Create" button.
6. Click the "Edit" button.
7. The "fixVersion" field should already be set, but if not, set it to the release for which the requirement is intended (e.g. "Guilin Release")
8. Set the following fields, if known.  Note: If not known, or not yet determined, wait until the information is known to set the field.
   1. Assignee - this should be one of the integration test leads, if more than one.  Use the template in the description field to document all of the test leads.
   2. IMPORTANT! Associated requirement or use case - add the reference(s) to the requirement or use case issue(s) (REQ-XYZ) to which this integration test task is associated using the "linked issues" field.  Use the relationship, "blocks". Note that the same integration test task may be linked to multiple requirements or use cases.
   3. Integration Test Plan Status
      • Note:  please add a link to your plan in the description field, where indicated by the template.  Similarly, add the names of the plan reviewers.
      • Not started
      • In process
      • In review
      • Completed
   4. Integration Test Status
      • Not started
      • In process (< 50%)
      • In process (>= 50%)
      • Completed
   5. Integration Test Time to Complete - Please keep this field updated with the expected time to complete testing.
9. If it has not yet been done, fill in the template contained in the "description" field.
10. Click "Update".

If Your Integration Test Task is Blocked

1. Open the Jira (REQ) that documents the integration test that is blocked and select edit.
2. Locate the "Integration Test Status" field and select "BLOCKED".  Save your changes.
3. Create a new issue to document the reason for being blocked.  For example, if the test is being blocked because of an issue in SO, then create a new issue in the SO project (SO-XYZ).
   1. Note: if the blocking issue is already documented in Jira, simply link that issue.  You do not need to create a new issue.
4. Link the new issue to your integration test issue (Blocked by).
5. IMPORTANT:  Add a comment to your integration test issue that explains the problem and include a reference to the new issue that you created.

Structure and Organization of Related Issues

The purpose of the Release Requirements (REQ) JIRA project is to create a single point from which all issues related to a particular release requirement may be found.  This association is nicely accomplished using the JIRA linking capability.  We will use two links, in particular:  1) "is blocked by"; and 2) "is related to".  Notice that we do not use "blocks".  This is because we want the REQ issue to be at the root of a network of related issues.  The REQ issue served an administrative function by creating a single connecting point for the network, while all of the other issues fill in the user story, features, tasks, and bugs.  

The diagram below shows an example of what this might look like.  It shows a release requirement (red box) with a chain of dependent issues.  The dependent issues are where the technical content is located.  However, notice that it also shows some "relates to" relationships (dotted lines).  These may include relationships to technical issues in other projects, such as a user story, but they may also include relationships to other release requirements. In any case, we are able to see all of the detail of the release requirement by beginning with the issue in the red box and following the links.

For a real example of how the issues should be organized relative to a release requirements JIRA issue, see  REQ-13 - Getting issue details... STATUS .

Frequently Asked Questions (FAQ)

Q: Is the Release Requirements (REQ) JIRA issue intended to replace issues documented in other JIRA projects?

A: No!  REQ served an administrative purpose by linking all of the technical issues (user story, features, tasks, etc.) that may be spread out over multiple JIRA projects to one location.  So, REQ does not replace your technical JIRA issues, but instead provides a single link to all of those issues (see diagram). 

Q: Should I use REQ to document technical content?

A:  No.  As mentioned above, REQ serves an administrative function, not a technical function.  It links all of the technical issues for a requirement to a single location.  Therefore, do not use REQ for technical content, but instead link the issues with technical content to REQ.

Q: May I have more than one release requirement JIRA associated with a requirement in the release requirements table in the wiki?

A: No – there should be a 1:1 relationship between the requirements in the release requirements wiki table and the release requirements JIRA. If you have more than one JIRA per requirement that probably means that your requirement is too vague, or too broadly stated.

Q: May I have the same technical issue, such as a user story, associated with more than one requirements JIRA issues?

Yes.  This is especially true if the issue is a user story, because a user story will likely have multiple requirements associated with it

Q:  May I have a release requirement that is not associated with a user story.

Yes.

Q: Should I make a requirements JIRA issue a dependency of another issue?

No.  As mentioned above, requirements JIRA issues should be at the root of the network.  If you want to associate another issue with a requirements issue, that is not a dependency, try using the "is related to" link.

For More Information

Please contact David McBride