amirbena / amirbena/code-review-skill
Define schema versioning
- Dominant language
- Python
- Stars
- 7
- Forks
- 2
- Avg merge
- 27m
- Merged PRs (30d)
- 188
Description
## Problem
Consumers need to detect and tolerate schema changes without silent
breakage. The repository's only existing `schema_version` precedent is
`scripts/packaging/package_manifest.py` (packaging-manifest domain: an
integer `schema_version`, fail-closed on an unsupported value) — a
reusable convention to adapt, not a design to couple review-output
versioning to.
## Goal
Define the versioning and compatibility policy for the output schema from
#67, informed by (but independent of) the packaging-manifest
`schema_version` precedent.
## Scope
- Add an explicit, required schema-version field to the #67 schema.
- Define compatible vs breaking change rules for review-output schema
evolution specifically (not a shared versioning architecture with
packaging).
- Define consumer guidance for unknown minor/major versions, e.g.
fail-closed on an unsupported major version, consistent with the spirit
of `package_manifest.py`'s fail-closed behavior.
## Non-goals
- Multi-version runtime translation.
- Coupling review-output versioning to the packaging-manifest
`schema_version` domain — cite it as prior art only, not a shared
implementation.
## Acceptance criteria
- Version field specified and required.
- Compatibility rules documented for the review-output schema.
- Deprecation/rollout guidance recorded.
- Prior-art citation to `package_manifest.py` recorded without merging the
two domains.
## Dependencies
Depends on #67 (open). Parent: #44.
## Validation
- Policy review; example document carries a version.
Contributor guide
Assessment
This issue has not been assessed yet.