This article is the eighth edition of the Advent of Patterns series. In this series, running from December 1st to December 24th 2024, I will document one design or programming pattern I have noticed recently. Read more about this series.
Software used for creating or publishing documents or files commonly implement version histories. Version histories allow a user to understand what has changed, when, and by whom in the history of a document.
When I was thinking about the software I use regularly that implements version history, three places came to mind:
- Git, a version control system widely used in software development;
- Google Docs, which I use for a lot of professional writing, and;
- MediaWiki, which I use to contribute to the IndieWeb wiki.
A fully-featured version control system should allow people to not only see what has changed, but rollback to a previous state. Being able to roll back to a previous version of a file is an example of “forgiveness” in software. If you make a mistake in a version of a document, or decide that you want to go back to a past version, having a document history is an invaluable tool.
Version histories are comprised of several states of history. These may be intentionally saved, or saved in the background as checkpoints. For example, Git histories log all commits. Commits are snapshots of a project at a given point in time. An engineer decides when to commit software to Git. For example, an engineer may need to change two files. Those files can be changed, then committed so that the changes become part of the version history in Git.
A commit contains a full log of the changes since the last commit, who made the commit, and when it was made. Descriptions are added to summarise the changes, allowing engineers to scroll through the history to find a specific change.
Here is an example of several commits in a Git project:
I can go back to all files in my Git project at any point in time to see how they existed at each commit.
If I have made changes that haven’t yet been committed that I want to roll back, I can always “roll back” to the last commit and continue my work from the last committed state. Rolling back is an essential part of a fully-featured version control system: users should both be able to see documents at a given point in history, and reset the state of the project to that state.
Version history is especially valuable for collaborative projects. If an engineer makes a change to a project that breaks something, the project can be rolled back to its last safe state while the changes are inspected and the requisite fixes are made.
MediaWiki uses the version history pattern too. When you make a change to a document in MediaWiki, a log is kept of the changes you made, when they were made, and by whom. This is displayed on a History page for the document. Users can view this page and click to see the difference between the current state and any previous state, or the difference between any change and its previous state.
Here is an example of a version history for the coffee page on the IndieWeb wiki:
MediaWiki, like Git, shows a change summary for the version that describes the number of characters changed. If you add more characters than you remove, the changed character number shows a positive number in green; otherwise, the changed character number is red. This lets you, at a glance, see whether a change added to or removed from the document.
Like Git, you can undo changes and go back to a previous state of a page in MediaWiki. This is an incredibly useful tool. If a change breaks a page, the change can be rolled back. If someone makes a destructive or unhelpful contribution, the change can be rolled back.
What are your favourite examples of version history?
