From 6c9914049e38d3c4821997ca307e20e49d0f5a7b Mon Sep 17 00:00:00 2001 From: Ryan Di Date: Fri, 20 Mar 2026 18:03:43 +1100 Subject: [PATCH] docs: jot down schema migration rules --- packages/excalidraw/data/SCHEMA_MIGRATIONS.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 packages/excalidraw/data/SCHEMA_MIGRATIONS.md diff --git a/packages/excalidraw/data/SCHEMA_MIGRATIONS.md b/packages/excalidraw/data/SCHEMA_MIGRATIONS.md new file mode 100644 index 0000000000..91eadf3350 --- /dev/null +++ b/packages/excalidraw/data/SCHEMA_MIGRATIONS.md @@ -0,0 +1,27 @@ +# Schema Migration Guidelines + +## Contract + +Each migration entry must declare: +- `version`: integer schema version (monotonic) +- `title`: short label +- `description`: required plain-language explanation of what changed +- `scope`: one or more scopes (`scene`, `library`, `clipboard`, `api`) +- `apply`: pure element transform + +## Versioning Rules + +- Use integer versions only (`2`, `3`, `4`, ...). +- `SCHEMA_VERSIONS.latest` must match the latest migration version. +- Add a new migration when behavior changes. + +## Scope Rules + +- Prefer explicit scopes. +- Use `ALL_SCOPES` only when the same transform is required for every boundary. +- If a migration was missing a scope but transform is unchanged, widening scope is allowed. + +## Field Stability + +Migrations must only rely on stable, persisted schema fields. +Do not read or write temporary/PR-only fields.