Version history

Problem Context

• Versions may be created by manual saves, autosave, publishing, imports, edits from multiple collaborators, merge operations, or restore actions.
• Users often seek a known good state after accidental edits, content regression, collaborator conflict, approval rollback, deleted section recovery, or configuration drift.
• Prior versions may include comments, author metadata, timestamps, branch or publish state, named milestones, deleted users, redacted content, permission limits, and retention cutoffs.
• Restoring an older version can affect current drafts, published content, collaborators, audit evidence, search indexing, external links, and downstream automations.

Selection Rules

• Choose version history when the user needs durable previous version snapshots with preview, compare, restore, name, or citation behavior.
• Use activity log when the primary task is investigation of actor, action, object, timestamp, source, result, IP, retention, and export evidence rather than restoring content.
• Use timeline when the primary task is reading a human-friendly sequence of events or milestones without exact snapshot comparison.
• Use undo when the action is recent, reversible in place, and does not require a persistent browser of previous versions.
• Use draft state when the current unfinished or unpublished work needs preservation, not when the user is browsing historical snapshots.
• Use publish workflow when the user is moving a selected version to live, scheduled, unpublished, or retired state.
• Use comments when users discuss, annotate, request changes, or resolve review threads attached to content.
• Use permission-denied state when a user cannot open, compare, name, restore, or download a version because access is missing.
• Expose a current version marker before every restore path so users know what will change.
• Provide compare or preview before restore when content loss, published behavior, or collaborator state could change.
• Label named versions, autosaved versions, restored versions, deleted authors, retention-limited rows, and permission-limited rows distinctly.
• Treat restore as creating a new current version unless the backend truly rewrites history, and explain the model.

Required States

• Default state with current version, previous version list, author, timestamp, and change summary.
• Named version state with editable or visible label and reason.
• Autosaved version state with system-created timestamp and author context.
• Version compare or diff state between current version and selected previous version.
• Preview selected previous version state before restore.
• Restore confirmation state that names the selected version and explains what becomes current.
• Restored state that shows the new current version and preserves access to the version restored from.
• View-only or permission-denied state for users who can inspect but cannot restore or compare restricted details.
• Deleted, archived, redacted, or retention-limited previous version state.
• Conflict state when current edits, unsaved draft, or concurrent collaborator changes exist.
• Loading, failed-load, offline, no versions, and mobile condensed-list states.

Interaction Contract

• Opening version history identifies the current version and keeps it visible while browsing previous versions.
• Selecting a previous version updates the preview or compare panel without changing the current content.
• Compare uses the same two versions named in the UI and states whether it shows text, layout, metadata, comments, or only a summary.
• Restore requires a confirmation when current edits, publishing state, permissions, or irreversible downstream effects could change.
• A successful restore states whether a new version was created and links back to the version restored from.
• Naming or renaming a version updates only the version label unless the UI explicitly supports editing content.
• Permission-limited rows reveal only metadata and actions the user is allowed to see.
• Retention-limited and deleted-author states explain missing history without implying user error.
• Mobile layouts preserve current version, selected previous version, compare, restore, and permission status without hiding the consequence copy.

Implementation Checklist

• Define the version record model: version ID or number, current flag, created timestamp, author, save source, named label, change summary, restore eligibility, retention class, permission scope, and comment or publish metadata.
• Separate version snapshots from activity events, timeline milestones, draft records, publish states, comment threads, and undo stacks in the backend and UI copy.
• Build a selected-version preview with clear current-versus-selected labels and a compare route for text, structure, metadata, file state, or configuration changes the product can honestly show.
• Implement restore confirmation, restored success state, permission-limited state, draft conflict handling, deleted-author handling, retention cutoff, failed-load retry, and mobile collapsed browsing.
• Preserve current version recoverability after restore when the backend supports append-only versioning, and state when it does not.
• Test long version names, many autosaves, same-minute edits, deleted authors, restricted viewers, comments attached to old versions, concurrent edits, offline retry, keyboard navigation, high zoom, and small screens.
• Log restore and rename actions as activity events without replacing the version history surface with the activity log.

Common Generated-UI Mistakes

• Calling an activity log or audit trail version history when it has no previous content snapshots.
• Using a timeline of milestones as a substitute for previewable or restorable versions.
• Relying on undo for recovery after navigation, collaboration, autosave, or elapsed time.
• Hiding the current version while users inspect previous versions.
• Restoring without preview, compare, confirmation, or conflict handling.
• Mixing named versions, autosaves, restored versions, and deleted-author versions without labels.
• Leaking private diff or author details to users who only have read or limited access.
• Hiding retention limits until after users cannot find a previous version.

Critique Questions

• Can users identify the current version and selected previous version at every point before restore?
• Does the UI show what changed, who changed it, when it changed, and whether the version is named or autosaved?
• What exactly happens to current edits, drafts, comments, publish state, and downstream links after restore?
• Can permission-limited users understand why compare, restore, or metadata is unavailable?
• Are retention cutoffs, deleted authors, archived versions, and failed loads explicit?
• Would an activity log, timeline, undo, draft state, publish workflow, comments, or permission-denied state be the better pattern for this task?