Compatibility Policy

Version rules keep the contract predictable while ota evolves, so migrations stay reviewable instead of surprising.

• version: 1 is the current contract version
• breaking schema changes require a version bump
• additive fields can be introduced within V1 when they do not break valid contracts

• unknown keys fail parsing
• there is no warning-only unknown-key mode today
• known fields are the contract surface; everything else is rejected

• document the replacement first
• keep the old shape working when feasible
• call out the migration path explicitly
• avoid silent removal

• do not rely on undocumented keys
• do not rely on silent fallback behavior
• do rely on explicit contract fields and versioned behavior changes

• know whether a new release can break old contracts
• understand whether a repo with unknown keys will still parse
• plan a migration for renamed fields