# Document Versions and Delete Impact

> 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.

Source: https://totalshiftleft.ai/help-center/product-documentation/requirements-document-versions

> **Applies to:** All editions (requirements review is basic on Free; full on Professional and Enterprise) · Web app and Desktop app · A role that can edit the project

## 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

| Term | What it means |
|---|---|
| **Upload new version** | A link on a document's row that uploads one file as that document's next version. |
| Version suggestion | After an ordinary upload, a question asking whether a file with a similar name replaces an existing document. |
| Replaced document | The older version. Its status becomes **Replaced by a newer version** and it can no longer be extracted. |
| **Changed — review again** | Rules whose content differs between versions. |
| **No longer stated — decide** | Rules the old version stated and the new one does not. |
| **Requirement changed** | A marker on a test whose requirement changed in the new version. The test still runs. |

## 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

| Kind of rule | Review decision | Tests | Old version's row |
|---|---|---|---|
| Unchanged | Carried over (approved, reviewed, or rejected) | Linked to the new requirement | Marked as replaced |
| Changed | New requirement goes to review | Linked to the new requirement and flagged **Requirement changed** | Marked as replaced |
| Added | New requirement goes to review | None yet | — |
| No longer stated | Untouched | Untouched | Listed for **Retire** or **Keep** |

Where you see it:

| Place | What it shows |
|---|---|
| Document list | The version chip, **Replaced by …**, **Being replaced by …**, and status **Replaced by a newer version** on the old document. |
| Test list | A **Requirement changed** marker on affected tests. Hover to see the old and new wording. |
| Review list and coverage | Only the current version's requirements are counted. The old version is not treated as "another document" that repeats or contradicts the new one. |

## 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

| Symptom | Why it happens | What to do |
|---|---|---|
| **Extract text** and **AI Parse** are unavailable on a document | It has been replaced by a newer version, and a replaced document cannot be re-extracted. | Extract the newer version instead. To make this one current again, delete the newer version. |
| **Upload new version** is missing on a row | The document is already replaced, a new version is waiting to be extracted, or the document is being processed. | Use the newest version's row, or wait for processing to finish. |
| No suggestion appeared for a similarly named file | The names were not similar enough, or the content was identical. | Use **Upload new version** on the old document's row instead. |
| The dialog shows every rule as changed | The new version rewrote most rules, or ids changed between versions. | Keep your document ids (such as `BR-014`) stable between versions; they are matched first. |
| A new version did not replace the old one | The new version produced no requirements (still extracting, or extraction failed). | Wait for extraction to finish, or fix and re-extract the new version. |
| "This document is being read right now. Try again when it has finished." | The document is being extracted. | Wait, then try again. |

## 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](/help-center/product-documentation/requirements-multiple-documents)
- [Duplicates and Conflicts Across Requirement Documents](/help-center/product-documentation/requirements-cross-document-duplicates-and-conflicts)
- [Importing and Reviewing Requirements](/help-center/product-documentation/importing-and-reviewing-requirements)
- [Requirements Traceability Matrix](/help-center/product-documentation/requirements-traceability-matrix)

## For administrators (self-hosted installations)

| Setting | Default | What switching it does |
|---|---|---|
| `RIE_DOCUMENT_VERSIONING_ENABLED` | `true` | `false` stops version suggestions after uploads, and linked versions are no longer compared or applied. |