Skip to content

Versions

Manuscript and Chapters

Both manuscripts and chapters can be given versions on top of the automatic git commits that happen on every save.

Versions can be nested to account for the diversity of writing experiences.

Here's a list of features I've considered (they apply to both chapter and manuscript versions):

  • Save current as new version
  • Save current as new sub-version: meaning it's the second sub-version at least unless a new version was just created.
  • Save and start new empty version (do-over)
  • Move/Copy version: a chapter to a different manuscript version mostly. This is easy in one direction but not so much in the other.
  • Continue older version: creates a new version (or sub-version?) after that version
  • Rename version
  • Delete version

Linear Timeline (No Branches)

To protect writers from merge conflicts and detached HEAD states, the engine avoids Git branches entirely.

Every save, version, and do-over exists on a single, continuous, forward-moving timeline. If the user wants to return to "Draft 1", the engine does not switch branches. Instead, it uses Git commands to pull the exact files from Draft 1 into the current physical working directory, and commits them as the new "front" of the timeline. The UI presents this as branching or restoring, but underneath it is a completely linear, safe history.

Set-Asides

Set-Asides should have their own repository, independent of the Manuscript so they can have versioning but can also be global.

A given version of the Set-Asides should also be freezable onto a version of the Manuscript (with the possibly to re-sync later on).

Outtakes

That makes it essential for Outtakes to have a memory of the chapter id they came from so that ophans can be tied back to that chapter in versions of the app where the chapter still existed.

It also means it's essential that the function to create chapter ids never gives the same id twice. Using standard UUIDs handles this cleanly. They are mathematically guaranteed never to collide, even if batch importing a thousand chapters at the exact same millisecond.

Chapter Do-Over

In the case of a do-over it might be worth it to consider orphaning the outtake anyway (or something else that signals that albeit the id is the right one, the version is most certainly not where it came from).

Maybe by having chapter ids be complemented by an iteration id. When a do-over happens, the chapter keeps its id but bumps its iteration id. Outtakes store both. That way the UI can just group outtakes from older iterations under a "Past Iterations" dropdown. They stay with the chapter but don't clutter up the fresh start.

This also brings up the fact that it might be worth it to have a message on do-over specifying that a do-over is for writing the same chapter again from the start and shouldn't be used for writing another chapter that happens to have the same number; in that case, the baest is to delete the old chapter and create a new one.