Introduction

Beginning with the Frankfurt release, we will document requirements in 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
   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

Issue 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).
   1. Note:  you no longer need to copy child issues
4. Modify the "epic name" and "summary" fields for your requirement. These may be the same, if you wish.
5. You may fill in the template in the "description" field now, or later if you prefer.
6. Click the "Create" button.
7. Click the "Edit" button.
8. 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")
9. 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)
   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.
   6. T-Shirt Size (defaults to M)
10. If it has not yet been done, fill in the template contained in the "description" field.
11. 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.
12. Click "Update".

Milestone Issue Updates

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.

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