42 lines
2.1 KiB
Markdown
42 lines
2.1 KiB
Markdown
# Canonical Model Backward-Compatibility Playbook
|
||
|
||
This playbook captures the policies and workflow required when evolving the canonical
|
||
`StellaOps.Feedser.Models` surface.
|
||
|
||
## Principles
|
||
|
||
- **Additive by default** – breaking field removals/renames are not allowed without a staged
|
||
migration plan.
|
||
- **Version-the-writer** – any change to serialization that affects downstream consumers must bump
|
||
the exporter version string and update `CANONICAL_RECORDS.md`.
|
||
- **Schema-first** – update documentation (`CANONICAL_RECORDS.md`) and corresponding tests before
|
||
shipping new fields.
|
||
- **Dual-read period** – when introducing a new field, keep old readers working by:
|
||
1. Making the field optional in the canonical model.
|
||
2. Providing default behavior in exporters/mergers when the field is absent.
|
||
3. Communicating via release notes and toggles when the field will become required.
|
||
|
||
## Workflow for Changes
|
||
|
||
1. **Proposal** – raise an issue describing the motivation, affected records, and compatibility
|
||
impact. Link to the relevant task in `TASKS.md`.
|
||
2. **Docs + Tests first** – update `CANONICAL_RECORDS.md`, add/adjust golden fixtures, and extend
|
||
regression tests (hash comparisons, snapshot assertions) to capture the new shape.
|
||
3. **Implementation** – introduce the model change along with migration logic (e.g., mergers filling
|
||
defaults, exporters emitting the new payload).
|
||
4. **Exporter bump** – update exporter version manifests (`ExporterVersion.GetVersion`) whenever the
|
||
serialized payload differs.
|
||
5. **Announcement** – document the change in release notes, highlighting optional vs. required
|
||
timelines.
|
||
6. **Cleanup** – once consumers have migrated, remove transitional logic and update docs/tests to
|
||
reflect the permanent shape.
|
||
|
||
## Testing Checklist
|
||
|
||
- `StellaOps.Feedser.Models.Tests` – update unit tests and golden examples.
|
||
- `Serialization determinism` – ensure the hash regression tests cover the new fields.
|
||
- Exporter integration (`Json`, `TrivyDb`) – confirm manifests include provenance + tree metadata
|
||
for the new shape.
|
||
|
||
Following this playbook keeps canonical payloads stable while allowing incremental evolution.
|