Document Versions and Delete Impact

Overview

Requirement documents change. When the BRD moves from v1 to v2, you need to know which rules changed, which are new, and which disappeared — without reviewing all of them again and without losing the tests you already built.

Shift-Left Studio lets you record a document as a new version of an earlier one. When the new version has been extracted, Studio compares it with the old one rule by rule:

• Unchanged rules keep their review decision and their tests.
• Changed rules go back to review, and the tests that covered the old wording are flagged Requirement changed.
• New rules are listed as added.
• Rules that are no longer stated are listed for you to retire or keep. Studio never retires them on its own.

Deleting a new version brings the old one back, and before any deletion Studio shows what it would remove.

Key concepts

Before you begin

• The earlier version must already be a requirement document in the same project.
• Only one file can be uploaded as a new version at a time, and it must be a requirement document (not test data).
• An AI provider must be configured, because the new version is extracted.

Step 1 — Upload the new version

Use either method.

Method A — from the document's row (recommended):

1. On the Requirement Documents tab, find the current version of the document.
2. Click Upload new version under its name.
3. Choose the new file. The row shows Uploading new version….
4. The new version is added and queued for extraction straight away.

Method B — answer the suggestion after an ordinary upload:

1. Upload the file with Choose requirement files or by dropping it.
2. If its name closely matches an existing document (ignoring things like "v1", "v2", dates, "final", "draft", or "copy") and its content is different, the Upload results panel asks: "Is BRD_v2.docx a new version of BRD_v1.docx?"
3. Click Yes, it replaces it to link them, or No, keep both to treat them as two separate documents.

Important: A similar name is only a question. Two documents can share a name and both be current, so Studio never links versions unless you say so.

Studio refuses the link if the two files are identical, belong to different projects, one is test data, or the older document has already been replaced by another version. If the file was stored but the link failed, the reason is shown next to the upload rather than as a failed upload.

Step 2 — Wait for extraction and open the comparison

1. While the new version is waiting or extracting, the old version's row shows Being replaced by <new file>.
2. When extraction finishes, the new version's row shows a chip such as v2 · replaces Order BRD v1.md · 1 changed · 1 to decide, and the old row shows Replaced by Order BRD v2.md.
3. Click either chip. The Versions dialog opens with the chain (for example, "v1 Order BRD v1.md → v2 Order BRD v2.md") and a summary: "Compared with v1 (…): 5 unchanged (4 review decisions carried over), 1 changed, 1 added, 1 no longer stated."

If the version has not been extracted yet, the dialog says "This version has not been parsed yet. What it changed appears once it has."

Step 3 — Review changed requirements

1. In Changed — review again, each entry shows the rule's title and ids, and the old value struck through next to the new value (for example, ≤ 100 → ≤ 50).
2. If tests covered the old wording, they are listed: "2 tests covered the old wording: …".
3. Open each listed test and update it if the new value requires it.
4. Click Tests checked when you are done. This clears the Requirement changed marker from those tests.
5. Review and approve the changed requirement in the review list, as you would any new requirement.

Studio compares what the document actually states — the field, condition, and value, or the quoted sentence — not the title the AI gave the rule. A rule is matched across versions by your id (such as BR-014) first, then by Studio's id, then by the rule's content, then by its sentence.

Step 4 — Decide what happens to rules no longer stated

1. In No longer stated — decide, each entry shows the rule, its statement, and how many tests it has.
2. Click Retire if the rule was withdrawn, or Keep if it still applies (for example, the author simply left a section out).
3. The entry then shows Retired or Kept. You can change the decision later.

The chip on the document row counts the rules still waiting for this decision ("N to decide").

Note: Studio never retires a dropped rule automatically. "The rule was withdrawn" and "the author forgot a section" look exactly the same from the document, so a person has to decide.

Step 5 — Check added requirements

The Added section lists rules that appear only in the new version. Review them in the review list like any newly extracted requirement.

Understanding the results

Where you see it:

Deleting a version and the delete preview

Before you delete any requirement document, the Delete document confirmation works out what the deletion removes and lists it:

• How many requirements only this document states, and how many tests link to them.
• How many requirements another document also states (these are kept there).
• How many test data rows and data sets it takes with it.
• What happens to versions:
  • Deleting a new version: "Order BRD v1.md becomes the current version again (3 requirements restored)". Every change made to the old version when the new one was applied is undone.
  • Deleting an older version: "This is an older version; Order BRD v2.md stays current".
  • Deleting a middle version of a chain links the newest version directly to the oldest.

Click Delete to confirm, or cancel. Deletion cannot be undone.

Troubleshooting

Best practices

• Always use Upload new version for a revised document rather than uploading it as a separate file. Otherwise the two versions are compared as different documents and every changed value is reported as a disagreement.
• Keep requirement ids stable across versions so rules are matched precisely.
• Work through No longer stated — decide promptly; the chip count on the row tells you what is left.
• Click Tests checked only after you have actually looked at the tests — it clears the marker from each test.
• Check the delete preview before deleting any document that other versions or tests depend on.

FAQ

Does a changed requirement keep its approval? No. A changed rule is a new statement and goes to review. Unchanged rules keep their decisions.

Is a test with Requirement changed disabled? No. The marker is information only; the test still runs until you update it.

Can I have more than two versions? Yes. Each new version replaces the one before it, and the Versions dialog shows the whole chain.

Related articles

• Working with Many Requirement Documents
• Duplicates and Conflicts Across Requirement Documents
• Importing and Reviewing Requirements
• Requirements Traceability Matrix

For administrators (self-hosted installations)