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.

Proposal – raise an issue describing the motivation, affected records, and compatibility impact. Link to the relevant task in TASKS.md.
Docs + Tests first – update CANONICAL_RECORDS.md, add/adjust golden fixtures, and extend regression tests (hash comparisons, snapshot assertions) to capture the new shape.
Implementation – introduce the model change along with migration logic (e.g., mergers filling defaults, exporters emitting the new payload).
Exporter bump – update exporter version manifests (ExporterVersion.GetVersion) whenever the serialized payload differs.
Announcement – document the change in release notes, highlighting optional vs. required timelines.
Cleanup – once consumers have migrated, remove transitional logic and update docs/tests to reflect the permanent shape.

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.