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
- 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.
- 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.
- 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.
- 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.
- Look at the linked work. In the same panel, every work item that was linked before the change carries a review flag.
- 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".
- 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
| Action | Who |
|---|---|
| See versions, diffs and flags | Anyone who can browse the work items |
| Mark reviewed | Anyone who can edit work items in either the requirement's space or the linked work item's space |
| Change which fields count | Space 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.