govoplan-core/docs/COMPATIBILITY_POLICY.md

GovOPlaN Compatibility Policy

This document defines the compatibility window that release tooling, module owners, migration authors, import/export providers, and API maintainers must preserve. It is the source of truth for deciding whether compatibility code can be removed.

Database Upgrades

• A released installation from every tagged 0.1.x version is a supported database upgrade origin.
• The recorded public release-baseline ledger starts at v0.1.7; earlier 0.1.x tags predate production installations. If an earlier tagged database is encountered, the release must provide or document a compatibility bridge instead of silently treating the database as a fresh installation.
• Released migration revision IDs and recorded release heads are immutable.
• Each release must prove an upgrade from every still-supported recorded baseline, as well as a fresh installation, before its tag is published.
• Migration-only reconciliation needed by an old database remains available for at least one subsequent major release cycle after the corresponding runtime compatibility path is removed.

The release-baseline format and commands are documented in RELEASE_DEPENDENCIES.md.

Configuration And Export Schemas

• Writers emit only the current schema version.
• Readers accept the current schema version and the previous two schema versions.
• Older input is rejected with a diagnostic that identifies its version and the required staged upgrade or conversion path.
• A module-owned configuration provider must version its input and output schema explicitly. It must not infer an old schema from missing fields once a versioned schema has shipped.
• Round-trip and upgrade tests must cover all three readable versions before a schema change is released.

This window applies to configuration packages, module-owned exports, and other portable GovOPlaN configuration artifacts. Domain interchange standards with their own compatibility rules remain governed by the owning module.

Runtime And API Aliases

• Compatibility aliases must emit an explicit deprecation diagnostic and point to the supported replacement.
• New callers must use the canonical contract. In-tree callers may not add new uses of a deprecated alias.
• Runtime imports, request fields, response fields, routes, and scope aliases carried for the 0.1.x split line are retired at 0.2, with migration notes.
• An alias may be removed earlier only when it never shipped in a tag or when a security fix requires removal. The release notes must state the exception.
• Database reconciliation code is not a runtime/API alias and follows the longer database window above.

Removal Checklist

Compatibility code can be removed only when all of the following are true:

1. The path is inventoried as a database bridge, portable-schema reader, or runtime/API alias.
2. Its minimum retention window has elapsed.
3. In-tree callers and published module manifests use the replacement.
4. Upgrade, import, or API regression tests cover the retained window.
5. Diagnostics and migration notes identify any staged action operators must take.

If one condition is not met, version-gate the compatibility path and record its planned removal release instead of deleting it.