Schema migration policy

The migration and versioning contract for persisted documents is stable enough to prepare 1.0.0-rc.1. It is not a functional blocker anymore.

Stability rule

Any evolution of a persisted QForm document must go through the public migration registry. This covers:

• the document envelope;
• the FormKit / Quasar schema;
• persisted values;
• builder settings;
• themes and visual presets.

No opportunistic reader for an old format should be added directly inside a Vue component or a store. Compatibility must remain centralized in the registry, testable and traceable.

What is still allowed before 1.0

Before 1.0.0, accepted fixes are limited to compatible regressions:

• fixing an existing migration;
• adding an explicit migration for a detected old format;
• improving input validation;
• documenting an edge case without changing the contract.

A change that introduces a document break must wait for a later version and declare a new migration path.

Expected evidence

Before release candidate promotion, run:

bun run migrations:check
bun run migrations:runtime:check
bun run schema-transfer:check
bun run api:contract:check

These commands confirm that versioned formats, future-version rejection and protections against dangerous keys remain covered.