Repository navigation
Commit d3eefef
authored
docs(storage): define compatibility rules for structural format changes (#1824)
## What it does
Adds a "Stored-format changes" section to docs/development.md and links
it from the "What a change needs" list in CONTRIBUTING.md. It sets the
rules for the next PR that changes the structure of a store Ovis owns:
an `ovis:` record in `localStorage`, or a bridge document in the state
directory such as `preferences.json` or `devices.json`.
That PR has to name the store's owner, the old and new shape, which
releases read and write each shape, and the contract that carries it. It
also has to keep five rules:
- tabs that are already open keep running their old code;
- migration stays passive, with no corrective PUT;
- data too new to read is never written over;
- `devices.json` fails closed;
- the supervisor's rollback restores code, not data.
The section also lists the tests such a change has to bring. It points
out that the `preferences.json` revision is not a schema version, and
that the transcript layout check in `server/session-history.ts` is not a
bridge-store migration.
## Why
Most stores carry no schema version. A careless structural change could
wipe settings through an old tab, overwrite another browser's data, or
reopen device pairing after a rollback. Writing the rules down before
that PR exists means it gets them right the first time.
## Verification
- Rebased onto current origin/main. Updated for the rename: the storage
keys are now `ovis:*`, where they were `herdr-web-ui:*`.
- `bun run check fast` passes.
- A code-review agent traced every code claim to its source
(`themeBoot.ts`, `settings.ts` `saveSettings`, `preferencesSync.ts`
`takePreferences`, `devices.ts` `error`/`gated`/`assertWritable`, the
rollback in `supervisor.ts`) and checked that every link and anchor
resolves. No HIGH findings. Its MEDIUM finding was that the two named
keys read as the complete list of browser records, so they are now given
as examples. Its LOW finding was that the too-new-devices sentence read
as current behaviour, so it now says "must".
Documentation only: no product code, wire type or test changes, so there
is no changelog fragment.1 parent b09a849 commit d3eefef
2 files changed
Lines changed: 55 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
106 | 106 | | |
107 | 107 | | |
108 | 108 | | |
| 109 | + | |
| 110 | + | |
109 | 111 | | |
110 | 112 | | |
111 | 113 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
604 | 604 | | |
605 | 605 | | |
606 | 606 | | |
| 607 | + | |
| 608 | + | |
| 609 | + | |
| 610 | + | |
| 611 | + | |
| 612 | + | |
| 613 | + | |
| 614 | + | |
| 615 | + | |
| 616 | + | |
| 617 | + | |
| 618 | + | |
| 619 | + | |
| 620 | + | |
| 621 | + | |
| 622 | + | |
| 623 | + | |
| 624 | + | |
| 625 | + | |
| 626 | + | |
| 627 | + | |
| 628 | + | |
| 629 | + | |
| 630 | + | |
| 631 | + | |
| 632 | + | |
| 633 | + | |
| 634 | + | |
| 635 | + | |
| 636 | + | |
| 637 | + | |
| 638 | + | |
| 639 | + | |
| 640 | + | |
| 641 | + | |
| 642 | + | |
| 643 | + | |
| 644 | + | |
| 645 | + | |
| 646 | + | |
| 647 | + | |
| 648 | + | |
| 649 | + | |
| 650 | + | |
| 651 | + | |
| 652 | + | |
| 653 | + | |
| 654 | + | |
| 655 | + | |
| 656 | + | |
| 657 | + | |
| 658 | + | |
| 659 | + | |
607 | 660 | | |
608 | 661 | | |
609 | 662 | | |
| |||
0 commit comments