Commonplace

Card Versioning and Copy-on-Write

Commonplace uses a copy-on-write approach to track changes to cards over time. This document explains how card versioning works and how it helps you manage your information.

What is Copy-on-Write?

Copy-on-write is a technique where modifications to an object create new versions rather than changing the original. In Commonplace, this means:

  • Cards are immutable (unchangeable) once created
  • All modifications create new versions of a card
  • The original version remains intact and accessible
  • Each version has a clear lineage back to the original

This approach provides a robust history of changes while maintaining data integrity.

How Card Versioning Works

Creating New Versions

When you edit a card in Commonplace, the system:

  1. Creates a new version of the card with your changes
  2. Maintains a link to the previous version
  3. Updates the card's metadata to reflect the change
  4. Makes the new version the "current" version in relevant collections

The previous version is preserved and can be accessed through the card's history.

Efficient Storage

To make this process efficient, Commonplace uses a copy-on-write approach:

  1. When you edit a card, the system creates a complete new copy with your changes
  2. The new copy maintains a reference to the previous version via its ID
  3. Each version is a complete, independent snapshot of the card at that point in time

This approach simplifies implementation while maintaining a clear history of changes.

Version Control

Each card maintains a version history that allows you to:

  • See when changes were made and by whom
  • Compare different versions to identify what changed
  • Revert to previous versions if needed
  • Branch versions for different purposes

This version control system is similar to what you might find in software development tools, but applied to knowledge management.

Propagation Control

When a card appears in multiple collections through references, you have control over how edits propagate:

Global Edit

When you make a global edit:

  • The change applies to the card in all collections where it appears
  • All references to the card show the updated version
  • The previous version becomes part of the card's history

This is useful when you're correcting information or making improvements that should apply everywhere.

Copy then edit

When you make a copy-then-edit:

  • A new version is created that's specific to the current collection
  • Other collections continue to show the previous version
  • The card now has a branched history

This is useful when you want to customize information for a specific context without affecting other uses of the card. Note that since this creates a new card instance, removing this card or the collection it's in will remove this customized version of the data.

Benefits of Copy-on-Write

The copy-on-write approach provides several benefits:

  • Data integrity: Original information is never lost or corrupted
  • Change tracking: Clear history of how information has evolved
  • Accountability: Record of who made what changes and when
  • Experimentation: Freedom to try changes without risk to existing data
  • Contextual variation: Ability to customize information for different contexts
  • Time travel: Access to information as it existed at different points in time

Working with Versions

TODO think about the below

As you use Commonplace, you'll interact with card versions in various ways:

  • Viewing history: Exploring how a card has changed over time
  • Comparing versions: Identifying differences between versions
  • Reverting changes: Returning to previous versions when needed
  • Branching: Creating variations for different purposes
  • Merging: Combining changes from different branches

Next Steps

TODO