Versions & branches

CompassDocs keeps a full revision history for every document. Each save that changes the title or content adds a version — with who made it, when, and an optional change note saying why. Nothing is ever overwritten: restores and merges add new versions on top of the timeline.

Open a document and click the clock icon in the header (or the “N versions” link in the byline) to open Version history.

Comparing versions

The history page opens with the latest change pre-selected. To compare any two versions, pick Original (older) and Modified (newer) with the radio buttons in the timeline.

• Rendered (the default) shows the changes in the document’s own layout: each changed section renders exactly as it does on the page — callouts, lists, tables, diagrams — with removed sections tinted red directly above their green-tinted replacements.
• Markdown shows the old version on the left and the new one on the right, line by line.
• Inline shows a single unified view with removed lines in red and added lines in green.

The source views include line numbers and word-level highlighting inside modified lines so you can see exactly which words changed; every view shows an +added / −removed summary and folds long unchanged stretches behind a “show” control. If the title changed between the two versions, that’s shown above the content diff.

A link can open the page on a comparison: /doc/{id}/history?from={versionId}&to={versionId} (to=current for the newest version). Only the document’s own version ids are honoured; anything else opens the default comparison. The read confirmation card uses this for Open in version history.

Change notes

When editing a document, fill in the Change note field (“what changed and why?”) before saving — it appears next to that version in the timeline. Notes survive the approval workflow: if your edit goes through the review queue, the approved version keeps your note and records who approved it (from 1.10.1 as a field on the version, beside who published it, not only inside the note). On a document that requires read confirmation, a note of at least 10 characters is required when the text changes (always for a material change; for an editorial fix while Program settings’ Require a reason for editorial fixes too is on, the default), and it is recorded on the compliance record as well.

Versions created by the system get automatic notes (“Created”, “Branched”, “Restored version 3 …”, “Merged draft branch”).

Read confirmation decisions

On a document that requires read confirmation, Version history shows what each saved edit did to existing confirmations: Asked everyone to re-confirm (amber) when the editor asked everyone to read the new text again, or Editorial (kept) (blue) when existing confirmations were kept. The full ledger, with reasons and counts, is the History tab of the document’s Read confirmation page. From 1.11.0 a version that came through the review queue names who submitted it beside who approved it, “Editorial (kept) recommended by Alex, approved by Priya”, and when the approver overrode the recommendation the line says what was recommended: “Editorial (kept) recommended material change by Alex, approved by Priya”.

Restoring a previous version

Editors with edit rights in the space see a Restore button on every older version. Restoring makes that version’s title and content current — as a new version at the top of the history, so you can always restore forward again. Restored versions carry a Restored badge and remember which version they came from.

Restores follow the approval workflow: on a published document in strict mode, an editor’s restore is submitted to the review queue for an approver to apply; approvers and admins restore immediately.

If the version you pick is identical to the current document, CompassDocs tells you there’s nothing to restore.

On a document that requires read confirmation, restoring a version whose text differs from the one people confirmed asks the same question as saving: whether the restore is an editorial fix (confirmations are kept) or a material change (everyone is asked to re-confirm), with a change note. The answer is recorded on the document’s History tab from source Restore. Restoring the confirmed version itself asks nothing. Through the API the restore is refused (428) until ack_policy and ack_reason are given; note sets the version note (see Change request decisions (API)).

In the app, Restore on such a version opens the same question the editor asks when saving, titled “Restore version 9 of a confirmed document?”: how many people have confirmed which version, the two cards (Editorial fix. Keep confirmations / Material change. Ask everyone to re-confirm), one sentence saying which choice CompassDocs guessed and why, a Show changes disclosure against the confirmed text, and the change note prefilled (“Restored version 9 from 2026-02-01”); what you leave there becomes the version note and the recorded reason, as for a merge. The button says what will happen: Restore. Keep confirmations or Restore and ask 42 people to re-confirm. Cancel restores nothing. A restore that goes to the review queue asks the submit question instead (the same cards, as a recommendation): your choice and note travel with the change request and the approver decides. Restoring the confirmed version itself, and restores on documents that do not require confirmation, ask the plain “Restore version 9?” question as before.

Draft branches

For bigger rewrites, work on a draft branch — a private working copy of the document:

1. Click the branch icon in the document header (or New draft branch on the history page). You land in the editor on a fresh copy.
2. Edit and save as often as you like. The branch has its own version history, and the live document is untouched.
3. When you’re ready, open the branch and use the banner at the top: Merge into original (with an optional change note) or Discard.

Branches are invisible everywhere readers look — they don’t appear in spaces, search, dashboards, Ask AI answers, or exports — and they can never be published directly; the only way a branch’s content goes live is a merge.

Merging follows the approval workflow too: approvers and admins merge instantly (the branch then moves to the Trash), while editors in strict mode submit the merge to the review queue — the branch stays open until the change is approved. The original document shows a notice while branches are in progress, linking to the history page where they’re listed.

Merging into a document that requires read confirmation asks the same question when the branch’s text differs from the version people confirmed, and the answer is recorded from source Merge. A merge also refuses to overwrite a live document that was saved while the branch was open (“The live document changed since this branch was created. Review it before merging.”): review the original (its own history shows what changed), bring the branch up to date if needed, and merge again. Without publish rights the merge becomes a change request as before, carrying your recommendation to the approver.

In the app the merge question reads “Merge this branch into a confirmed document?”, with the two cards, the guess, Show changes and a change note prefilled from the banner’s note (or the branch’s title). The button reads Merge. Keep confirmations or Merge and ask 42 people to re-confirm; the note becomes the version note and is recorded as the reason on the document’s History tab (source Merge). A merge that goes to the review queue asks the submit question instead: your choice and note travel with the change request as your recommendation, and the approver decides.

Who changed what

Every version records its author, and every restore, branch, and merge is written to the audit log with the actor, document, and IP address — document.restore_version, document.branch_create, and document.branch_merge — alongside the existing document events.