Policy for 1.0 and later releases: documented public contracts are the baseline. Minor and patch releases preserve them; planned incompatible changes require a major release and advance notice.
What needs compatibility review?
Review the documented configuration, scenarios, selectors, CLI output and exit codes, HTTP fields and errors, metrics, journal schemas and supported environments. Defaults, action ordering, authentication, units, labels and machine-readable reasons are part of that review. Application versions, HTTP route versions and persisted schemas are separate identifiers.
Even an optional field can break strict consumers; consider enum values, fixed CSV columns and metric cardinality. Internal Python classes, human diagnostic wording, implicit CLI abbreviations and undocumented behavior are not stable interfaces, but known operational effects must still be explained. Machine-readable reasons stay in English and are distinct from human diagnostics.
Announce before removing
- Document the old behavior, affected users, replacement and risks in the pull request, with a link to the relevant baseline.
- Publish the replacement and notice in at least one released version while the old documented behavior remains usable. A development-branch notice is insufficient.
- Name the announcing release and earliest removal release. Removal must happen in a later release. If unscheduled, say so and announce the target before removal. There is no calendar-based support window or automatic removal.
- Before removal, verify migration for the stated source/target versions, update guides and examples, and publish rollback limits and test evidence for maintainer review.
Put notices in the affected guide and published release notes, linked from the release’s pull request. Runtime warnings can supplement them but must not corrupt structured outputs. No warning mechanism is introduced here. Pin exact versions and read intervening notices when skipping releases; indefinite support and backports for every release are not promised.
Urgent exceptions
A confirmed security exposure or risk of data loss can justify an immediate incompatible correction. The maintainer must explain why waiting is unsafe, affected versions, operational impact, replacement or recovery, and rollback restrictions in the corrected release. Withholding exploit details must not hide the operational impact. Convenience, cleanup or a generic “bug fix” label does not waive advance notice.
Migration and rollback
Configuration and command changes need before/after examples, validation, changed defaults and action-selection consequences. Existing rules must not be silently reinterpreted. The selector and comparison choices were introduced in 0.0.80 and are retained in 1.0.
HTTP and metric changes must identify consumers and explain coexistence or versioning. The /v1 prefix does not allow silent changes in meaning; deciding when another route version is needed remains separate work.
Before enabling an incompatible writer, publish an exact application-version/schema reader/writer table, mixed-history tests, backup instructions and rollback boundaries. Prefer lossless adaptation on reading. Required physical conversion must be explicit, preserve original bytes, use separate output, support simulation, verify counts and identities, and explain interruption recovery. Unknown formats must fail explicitly.
The optional audit-migrate command converts journal schemas 1/2 to 2; it does not migrate configuration or action state, or replace the active journal. It does not certify arbitrary upgrades or downgrades.
Identify all persistent paths and writers, stop writers for a consistent backup, preserve permissions and test against copies. Verify collection, state, history and exports before resuming. Before rollback, preserve post-upgrade data separately and verify the older reader/configuration against copies. A restored backup can exclude newer events; document any data-preservation limit and recovery path. Never replay actions because records were migrated. A same-version copy test does not certify a cross-version deployment upgrade.
Required change notice
Replace these placeholders with concrete versions when publishing; this is a template, not a scheduled removal. Explain any inapplicable field.
Affected interface and old behavior:
Reason for the change:
Notice/replacement release:
Earliest removal release (or not yet scheduled):
Affected and tested source -> target versions:
Replacement and before/after example:
Validation and migration commands:
Persistent data, backup and interruption recovery:
Rollback limits and treatment of post-upgrade data:
Regression/upgrade evidence and known limits:
Tracking issue or pull request:
Urgent exception justification (if applicable):The GitHub policy is the maintained reference. The roadmap separates completed acceptance from outstanding prolonged observation.