amirbena / amirbena/code-review-skill

Define schema versioning

Open
#68 0 comments 0 reactions 1 assignee Claimed by @amirbena View on GitHub
area:platform-contracts maintainer-led priority:P1 type:feature
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.