70 lines
3.2 KiB
Markdown
70 lines
3.2 KiB
Markdown
# 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.
|