How to track requirement changes in Jira

By Jake Marsh · Updated

To track requirement changes in Jira, install Tracestitch and turn on tracking for the space in Requirements > Settings. Every change to a requirement's summary, description or chosen text fields becomes a new version you can compare word by word in the Traceability panel. At the same time, each story, test or bug linked to it is flagged "Changed: v1 to v2" until someone clicks See what changed and Mark reviewed.

Why Jira needs help here

Jira's History tab records that the description changed and keeps the old value, but it shows the whole field before and after, which is hard to read on a long requirement. More importantly, nobody linked to the requirement is told. The developer on the story and the tester writing the test keep working from the old wording until someone notices. Tracestitch puts the change on their work items.

Steps

  1. Turn on tracking. A space admin opens Requirements > Settings, ticks Track requirements in this space, picks the Work item types that are requirements and an ID prefix, and clicks Save.
  2. Choose what counts as the requirement text. The summary and description always do. Under Extra text fields that are part of the requirement, add fields such as acceptance criteria. Click Save; Tracestitch rescans the space.
  3. Edit a requirement in Jira. When the text changes, Tracestitch records the next version. Changing only the status or formatting (bold, colours) doesn't create one.
  4. Open the requirement's Traceability panel. Under History you see each version with when it changed and who changed it. Pick two versions and click Compare text: added words are bold, removed words are struck through.
  5. Look at the linked work. In the same panel, every work item that was linked before the change carries a review flag.
  6. Review from the story or test. Its Traceability panel lists the requirements it traces to. A changed one shows "Changed: v1 to v2" with See what changed and Mark reviewed. After marking it, the panel says "Up to date with version 2".
  7. Find everything waiting for review. Search Jira with reqSuspect > 0, or tick Only with links to review on the Traceability matrix tab.

An example

PAY-REQ-7 says "Customers can cancel an order within 24 hours". Someone edits it to "within 2 hours, unless it has shipped". Tracestitch records version 2. Story PAY-210 and test PAY-233 were linked before the edit, so both now show "Changed: v1 to v2". The tester clicks See what changed, sees "24" struck through and "2" and "unless it has shipped" in bold, updates the test, and clicks Mark reviewed. The story stays flagged until its developer does the same.

Who can do what

ActionWho
See versions, diffs and flagsAnyone who can browse the work items
Mark reviewedAnyone who can edit work items in either the requirement's space or the linked work item's space
Change which fields countSpace admins and Jira admins

New links are never flagged: a story linked after version 2 starts out up to date.

Things to know

  • Existing requirements start at version 1 when tracking is turned on. Earlier edits from Jira's own history aren't imported.
  • A change synced before a rescan finishes can flag its links once more after you change the extra text fields.
  • Settings changes, scans, baselines, folder changes and reviews are listed in the Activity tab for space admins.

What it costs

Tracestitch is $10 a month for up to 10 users. From 11 users, every user is billed at $2.05 a month, with lower rates on larger sites. Atlassian bills it and there's a free trial. Pricing and the install link are on the Tracestitch page.

Tracestitch: Requirements and Traceability for Jira

Requirement IDs, versions and readable diffs on Jira work items. Baselines, a traceability matrix and suspect links after changes. From $10 a month for up to 10 users.


Questions

Can I get a notification when a requirement changes?

Tracestitch doesn't send emails. The flag shows on each linked work item's Traceability panel, and you can save reqSuspect > 0 as a Jira filter with a subscription so Jira emails you the list.

Does reformatting a requirement count as a change?

No. Only the words count. Bold, colours and Jira re-saving the same text don't create a version.

Can I see a requirement as it was on a given date?

Pick that version under History. To keep the whole set as it was on a date, take a baseline.

Which requirement IDs change when I edit?

None. IDs never change and are never reused, even when a requirement moves or the prefix changes.


More Tracestitch guides


More Jira guides