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:

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. t-shirt size,
   2. milestone scorecards,
   3. milestone TSC approvals,
   4. arch subcommittee review status
   5. 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

1. Navigate to  REQ-1 - Getting issue details... STATUS
2. Select More==>Clone++
3. Follow the steps in the dialog to clone the issue in the same project (i.e., REQ).  Make sure that the checkbox, "copy issues in epic" is selected.
4. Modify the "epic name" and "description" fields for your requirement.
5. Set the "Fix Version" field to the release name for which the use case is intended (e.g., "Frankfurt")
6. Set the "Assignee" field to the requirement owner.
7. If the requirement has other requirements or tasks as dependencies, add the requirements in the "Issues in Epic" field.
8. Add a link to the JIRA issue in the appropriate column of the table on the release requirements page.
9. Once the TSC has determined the priority for the requirement (0 - 4), set the value in the "TSC Priority" field.
10. The template includes three sub-tasks for the TSC approvals at MS1, MS3, and MS4.  As these approvals are achieved, add a comment to the sub-task with a link to the approval documentation and mark the task as done.

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