How to track changes to requirements: versions and history

Published 22 October 2026

To track changes to requirements, give every requirement a permanent ID and a history of its own — what it said, what it says now, why it changed, who decided and when — and record which versions were agreed together. A document’s version history alone does not answer “when did this rule change, and who agreed to it?”. Below are the three kinds of version, what a requirement’s history needs, an example, deleted and deferred requirements, how to keep the history in Word, Confluence, Jira, git and a spreadsheet, and the ways it goes wrong.

What if the User Story changes later, how is it updated and kept as an artifact? I’ve seen many teams just open a new ticket/feature request/bug report instead of keeping track of the original story.

— from “How do you keep track of a requirements document on an agile team?”, viewed over 25,000 times on Software Engineering Stack Exchange, 2012

Three kinds of version

Most tools keep only one of the three. Karl Wiegers on the difference: “some tools will retain all historical versions of every individual requirement, whereas version control tools generally maintain previous versions of entire documents” (Handling Requirements for Multiple Releases). A document’s history tells you that page 12 changed on 17 June; it does not tell you which requirement changed, why, or on whose decision. A baseline is covered in requirements baseline; this page is about the first kind, and how it connects to the other two.

What a requirement’s history needs

• A permanent ID. Never reused, never renumbered. “If you don’t have unique and persistent labels on requirements, design elements, and other system elements, there’s no way you can document the connections between them,” Wiegers writes (Links in the Requirements Chain).
• A version number of its own, separate from the document’s.
• The old wording and the new, both kept in full.
• The reason — the change request, the problem it solves.
• Who decided, and when — a name and a date, or a decision ID.
• What changed with it: the acceptance criteria, the rules, the tests.

The old IEEE standard for requirements specifications asked for the same thing at document level: approved changes should “Provide an accurate and complete audit trail of changes” and “Permit the review of current and superseded portions of the SRS” (IEEE 830-1998). One commenter’s version of it: “include dedicated sections in the requirements document which call out the changes that have been made, the date, the person who gave authority for the change, and the impact” (r/businessanalysis, 2020).

Requirement change history example

The payment reminder from the customer portal used across these templates. Version 2 came with the part payments change (CR-10):

FR-016  Payment reminder

Version 2   requirements 1.4, 17 June
One reminder, seven days after the due
date, for every invoice not paid in
full.
Changed by:  CR-10, part payments
Decided:     D-7, finance lead,
             16 June
Why:         a partly paid invoice
             would never be chased
Also:        acceptance criterion 4
             added; RULE-06 version 2

Version 1   requirements 1.0, 28 January
One reminder, seven days after the due
date, for every open invoice.
Decided:     D-1, finance lead,
             28 January

Someone who finds the January wording in an old ticket can see that it was the rule, that it changed, when, why and on whose decision. The document keeps a revision table as well — one line per version, naming the requirements each change touched:

The two views answer different questions: the table, what changed in each version; the requirement’s history, how one requirement got to where it is. The change log keeps one line per requirement changed, and the change request log the requests behind them.

Deleted, deferred and rejected requirements

A requirement that is dropped should not disappear. Wiegers’ list of statuses keeps it visible: “Deferred (the requirement will be implemented in a future release)”, “Deleted (you decided not to implement it at all)”, “Rejected (the idea was never approved)” (Measuring Requirements). His reason: “Deleted requirements, rejected requirements, ideas, and potential requirements for the future have a way of resurfacing before the project is finished. You don’t want to lose sight of the fact that these requirements once were proposed or considered to be in scope.”

Keep the ID, the last wording and the status, with the decision that set it. Saved cards in the portal were decided as “Won’t have this time” in January; when someone asks for them again, the answer and its reason are already there.

How to track requirement changes in Word, Confluence, Jira and git

Each has its own trap. In Jira, the history is there but the current requirement is hard to find: “Issue tracker gives you a history of what, when and why it changed but it’s not realistic to be a source of truth of current status” (Project Management Stack Exchange, 2018). In Confluence and git, the history is per page or per file, not per requirement, unless each requirement has a place of its own. More on each in requirements in Jira, requirements in Confluence and requirements in git.

Tracking requirement changes in agile

In an agile team, requirements tend to live in stories, and a change becomes a new story. The person who started one thread described the result: “The problem comes in down the road where the requirements are spread over thousands of user stories, and requirements are difficult to find” (r/agile, 2020).

The fix is to keep a requirement — a description of what the product does now — apart from the stories that build or change it, and link them. One Stack Exchange answer: “What works well in my experience is linking the business requirements and user stories in both directions,” because “It also provides a way for new project members to get to speed since they have something to review to get the history behind why the software does what it does” (Stack Exchange, 2014).

How requirement change history goes wrong

• History without a current version. The tracker shows every change, but nobody can say what the requirement says today.
• A current version without history. The document is overwritten; the old wording is gone, and so is the answer to “what did we agree in March?”.
• History without reasons. The diff shows what changed, not why or on whose decision.
• History left in an old tool. “There was a Trello board that no one bothered to archive when the project switched to Jira” (Hacker News, 2026).
• The same requirement in three places. One copy is updated, the others are not, and each has a different history. Write each requirement once and refer to it by ID.

When the history and the work part ways, that is spec drift.

Checklist for tracking changes to requirements

1. Every requirement has a permanent ID that is never reused.
2. Every requirement has its own version number.
3. Every change keeps the old wording, the new wording, the reason, the decision and the date.
4. The document has a revision table that names the requirements each version changed.
5. Each baseline records which versions were agreed together.
6. Deleted, deferred and rejected requirements keep their ID, wording and status.
7. Stories and tests link to the requirement and the version they were built against.
8. Each requirement is written in one place; everything else refers to it.

Where Specroot fits

This is the problem Specroot works on: each requirement kept with its versions, the decision behind every change, and the baselines it was agreed in — so that “what did it say, and who agreed?” has an answer. Specroot for agencies and consultancies.