Module migrate 

Data format versions and migrations. A brain’s files (entries, tags.md, last-id, a project’s cards and registry) follow a format numbered in its format file, FORMAT for those this version writes. Formats change only with a migration, which brings a brain from the one before: when a brain is opened to be changed, and for every registered brain on kb update, the migrations it lacks run in order, under its write lock, after a copy of it goes to the user’s cache. A brain in a newer format than this version knows is refused entirely, read or written: an older kb reading a teammate’s .brain/ from git would misread what it doesn’t know, and rewriting it would lose it.

To change the format: add the step to MIGRATIONS, bump FORMAT, add a fixture of the old format to the tests, and say so in the release notes. A step is never removed, since a brain may skip versions, and works on the files’ text rather than today’s types, which later formats change.

Structs

Migration

One step from a format to the next.

TooNew

A brain in a format newer than FORMAT: written by a newer kanbrain, so this one leaves it alone.

Constants

FORMAT

The data format this version reads and writes.

FORMAT_FILE

The file beside a brain’s entries holding its format. A brain without one is format 1: from before formats were numbered, which the first format is.

MIGRATIONS

Every step, in order: MIGRATIONS[i] brings a brain from format i + 1 to i + 2.

Functions

check

Refuses, with TooNew, a brain in a format newer than FORMAT.

format_of

The format of the brain in dir.

migrate

Brings the brain in store to FORMAT, and returns what it did, one line each; nothing for a brain already there.