10. Versions and migrations
designVersion is "<major>.<minor>".
10.1 The version number#
designVersion is "<major>.<minor>". This document describes "1.0".
- A minor version adds optional properties, node types or operations. Older builds of the same major version read the file: unknown properties are kept, unknown types are placeholders, unknown operations are skipped and kept (sections 5.12, 9). Writers write the highest minor version they know only when they write something that needs it.
- A major version changes the meaning or shape of existing data. Older builds refuse it; newer builds migrate from it.
10.2 Classification on open#
designVersion |
Result |
|---|---|
| empty file | A new document (3.1). |
| not JSON | Recovery (9.3), else refused. |
| missing | Read as "1.0" with the warning The file has no designVersion; reading it as 1.0.; written with the next change. |
known (1.0) |
Read. |
same major, newer minor (1.3) |
Read and edited, tolerantly; the status strip says Written by a newer UI Designer (format 1.3): some content may be shown as placeholders. |
| older major with a migration | Migrated in memory (10.3); the file is rewritten in the new format with the next change, after a confirmation. |
newer major (2.0) |
Refused for editing: This file uses format 2.0, written by a newer UI Designer. Update the extension to edit it. “Open as Text” is offered. |
anything else ("abc", a number) |
Refused: The file has an unknown designVersion "abc". |
10.3 Migrations#
A migration is a module with:
| Member | Meaning |
|---|---|
from |
The version it reads, e.g. "1" (major) |
to |
The version it writes, e.g. "2" |
describe |
One sentence shown in the confirmation and in the history note. |
migrate(file) |
A pure function from the old top-level object to the new one: the tree and every WAL line are converted, so the new file folds to the same document. |
Migrations are chained: a file of format 1 opened by a build of format 3 runs 1→2, then 2→3. The chain is
empty in 1.0.
A migration rewrites lines of the WAL, so like consolidation it cannot be merged with branches that still
write the old format. ud upgrade migrates and consolidates in one step; run it on the main branch and commit
it on its own. Unknown members and unknown operations are carried through a migration unchanged.
10.4 Rules for later formats#
- Never reuse a property name, operation name or id prefix with a new meaning; add a new one.
- A new property has a default that keeps old files meaning what they meant.
- A new operation must be safe to skip: a reader that skips it shows a document that is less complete, not a wrong one.
- Each format version has its own schema file (
design-<major>.<minor>.schema.json), and the previous one stays published.