{"slug":"version-history","meta":{"title":"Version History","slug":"version-history","kind":"pattern","summary":"Previous states of a record kept, listed and restorable — so an edit is never the destruction of what came before.","problem":"Someone overwrites a paragraph, a price or a whole document and there is no previous copy. The information existed an hour ago and now exists nowhere, and the only recovery is whoever happens to remember it.","family":["edit","recover"],"data_shape":["record"],"principles":["orientation","consistency"],"interaction":["disclosure","navigation"],"density":"low","complexity":"high","status":"stable","visibility":"public","use_when":["The record holds composed content — text, configuration, a document, a template.","The system autosaves, which removes the natural \"before\" that explicit save provided.","Several people edit the same record, so a change can surprise someone who did not make it."],"avoid_when":["Every change is already an append-only event and nothing is ever overwritten.","The record is trivially reproducible from its source.","Storage or privacy rules mean old content must not be retained."],"alternatives":[{"slug":"activity-timeline","when":"People need to know who changed what, not to read or restore the old content."},{"slug":"autosave","when":"You have not yet solved durability at all — do that first; history is its companion."}],"ask_leo":"Give this record a version history.\n\n- Snapshot on meaningful boundaries, not on every keystroke: when the record\n  is saved, when an editing session ends, or when the editor changes.\n- List versions newest first with who made the change and when, and give each\n  one a short summary of what changed rather than only a timestamp.\n- Let someone open a version read-only, and clearly mark that they are looking\n  at an old version and not the current one.\n- Show a comparison between a version and the current state, highlighting what\n  was added and removed.\n- Restoring creates a NEW version whose content is the old one. Never delete\n  the versions in between — restore must itself be undoable.\n- Collapse consecutive versions by the same person within a short window into\n  one entry, so a working session is one row rather than forty.\n- Say how long history is kept, and never silently drop versions people can\n  still see referenced.\n","related":[{"title":"Autosave","url":"/patterns/autosave","summary":"Why continuous saving makes history mandatory rather than optional."},{"title":"Activity Timeline","url":"/patterns/activity-timeline","summary":"The sibling — timeline records actions, history records content."}]},"body":"## Anatomy\n\n```\n  Versions                          ┌─ viewing v6 (read-only) ───────┐\n  ● Current — Dana, 2h ago          │ Site access is via the rear    │\n  ○ v6 — Dana, 3h ago               │ gate. Ask for Marek…           │\n      \"rewrote access notes\"        │                                │\n  ○ v5 — Priya, yesterday           │ [ Compare to current ]         │\n  ○ v4 — Dana, 3 days ago           │ [ Restore this version ]       │\n      (12 edits in one session)     └────────────────────────────────┘\n```\n\nFour obligations:\n\n1. **Snapshots on boundaries**, not on keystrokes. Otherwise the list is\n   thousands of entries and useless.\n2. **A summary per version.** A list of identical timestamps makes people open\n   every one.\n3. **Restore is a new version.** Rolling back must not destroy what it rolls\n   back past, or restore becomes as dangerous as the overwrite it fixes.\n4. **An unmistakable read-only marker** when viewing an old version, or someone\n   will edit history and be confused when it does not save.\n\n## Why it works\n\nIt converts editing from destruction into accumulation. Once nothing is lost,\nseveral other things get cheaper: people are willing to make bigger changes,\ndisagreements about \"what did it say before\" become checkable, and\n[autosave](/patterns/autosave) becomes safe to adopt.\n\nThat last connection is the important one and the most often missed. Autosave\nwithout history is not a feature, it is a hazard — it removes the moment of\ndeliberation that explicit save provided while providing nothing in its place.\nThe two patterns are halves of one design.\n\n## The diff is the product\n\nA list of versions is mildly useful. A **comparison** is what people actually\nwant, because the question is almost never \"what did version 4 say\" — it is\n\"what changed between then and now\".\n\nIf you build only one thing beyond the list, build the diff. It is also what\nmakes the summaries writable: once you can compute what changed, you can\ndescribe it.\n\n## Getting it wrong\n\n- **A version per keystroke**, producing a list nobody can navigate.\n- **Timestamps with no summary**, so finding the right version means opening\n  ten.\n- **Destructive restore**, which discards the intervening versions and makes\n  rollback a decision people are afraid of.\n- **No read-only marker**, so people edit an old version and lose the work\n  twice.\n- **Silent retention limits.** Versions vanishing after thirty days, discovered\n  on the day someone needs day thirty-one.\n\n## Exemplars\n\n**Google Docs version history** is the reference: named sessions rather than raw\nsaves, a readable diff, and restore that itself creates a version. It is also\nthe clearest demonstration of the autosave pairing — the history is what makes\nnever pressing save acceptable.\n\n**Git** is the maximal version of the pattern, and the useful lesson from it is\nsocial rather than technical: history is most valuable when every change carries\na human description of *why*, not just a record of *what*.\n\n**Notion's page history** shows the retention trap handled explicitly — the\nlimit is stated in the interface and tied to the plan, rather than discovered.\n\nThe extractable rule: **history is what makes editing safe, and the diff is what\nmakes history usable.** A list of versions without a comparison is an archive\nnobody opens.\n"}