diff --git a/docs/COMPATIBILITY_POLICY.md b/docs/COMPATIBILITY_POLICY.md new file mode 100644 index 0000000..d410674 --- /dev/null +++ b/docs/COMPATIBILITY_POLICY.md @@ -0,0 +1,69 @@ +# 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. diff --git a/docs/CONFIGURATION_PACKAGES.md b/docs/CONFIGURATION_PACKAGES.md index c4e1407..1cce041 100644 --- a/docs/CONFIGURATION_PACKAGES.md +++ b/docs/CONFIGURATION_PACKAGES.md @@ -69,6 +69,11 @@ Required package metadata: - migration or transformation rules for older package versions - provenance, export source metadata, and signature metadata +Portable configuration schemas follow `COMPATIBILITY_POLICY.md`: providers +write only their current schema version and read that version plus the previous +two versions. Older input must produce a version-specific staged-upgrade +diagnostic. + Configuration fragments are interpreted only by the module that owns them. For example, workflow imports workflow definitions; forms imports form schemas; mail imports mail templates and delivery defaults; payments imports payment diff --git a/docs/DOCUMENTATION_MAP.md b/docs/DOCUMENTATION_MAP.md index 890adfc..3ec3d0c 100644 --- a/docs/DOCUMENTATION_MAP.md +++ b/docs/DOCUMENTATION_MAP.md @@ -9,6 +9,7 @@ operator, and roadmap pages. | Topic | Canonical document | Notes | | --- | --- | --- | | Module architecture and kernel contracts | `MODULE_ARCHITECTURE.md` | Stable module contracts, API efficiency contracts, durable boundary decisions, lifecycle, and WebUI contribution rules. | +| Compatibility policy | `COMPATIBILITY_POLICY.md` | Supported database upgrade origins, portable-schema read/write windows, runtime/API alias retirement, and compatibility-code removal criteria. | | RBAC and resource access | `ACCESS_RBAC_MODEL.md` | Current permission, role, API-key, and resource-access model. | | Governance hierarchy | `GOVERNANCE_MODEL.md` | System, tenant, user/group, campaign policy inheritance and admin UI structure. | | Policy decision DTOs and provenance | `POLICY_CONTRACTS.md` | Shared explain/provenance shape; module-specific policy docs should link here. | diff --git a/docs/MODULE_ARCHITECTURE.md b/docs/MODULE_ARCHITECTURE.md index 8117b84..c74094c 100644 --- a/docs/MODULE_ARCHITECTURE.md +++ b/docs/MODULE_ARCHITECTURE.md @@ -74,6 +74,10 @@ The compatibility/deprecation plan for the current split line is: - reject new cross-module imports that bypass manifests, capabilities, events, or public module APIs +The retention windows and removal checklist for database bridges, +configuration/export schemas, and runtime/API aliases are defined in +`COMPATIBILITY_POLICY.md`. + ## Stable Kernel Contracts The following contracts are the baseline API that modules can rely on: diff --git a/docs/RELEASE_DEPENDENCIES.md b/docs/RELEASE_DEPENDENCIES.md index 9e16682..75103a7 100644 --- a/docs/RELEASE_DEPENDENCIES.md +++ b/docs/RELEASE_DEPENDENCIES.md @@ -803,6 +803,12 @@ collecting release evidence. ## Migration Baselines +Release migration support follows `COMPATIBILITY_POLICY.md`: every tagged +`0.1.x` installation is a supported upgrade origin, released revision IDs are +immutable, and migration-only reconciliation remains available for at least one +subsequent major release cycle after the matching runtime compatibility path is +removed. + Development migrations may be small and numerous while a feature is moving. GovOPlaN keeps those detailed migrations on an explicit development track and publishes reviewed release shortcuts on the release track. Before a stable