bump registry schema
Bump the registry schema version
Section titled “Bump the registry schema version”registry.yaml has a version integer field gated by
registry.schema.json’s const: <N>. The @petrova/cli build
exposes SUPPORTED_REGISTRY_VERSION matching that constant.
If the registry’s shape changes in a way consumers cannot silently absorb — a removed field, a renamed key, a tightened enum — bump the version. Additive changes (new optional fields) do not require a bump.
When to bump
Section titled “When to bump”| Change | Bump? |
|---|---|
| New optional field with default | No |
| New required field | Yes — old CLIs would write entries missing it |
| Removed field referenced anywhere | Yes — old CLIs would read it as undefined |
| Renamed field | Yes |
| Tightened enum (smaller value set) | Yes — old CLIs may write a now-invalid value |
| Loosened enum (additional values) | No |
Procedure
Section titled “Procedure”- Update
registry.schema.json: bump theversion.constfrom<N>to<N+1>. Adjust any other schema changes you’re shipping in the same PR. - Update
registry.yaml: bump the top-levelversion: <N>to<N+1>. Hand-fix any entries the new schema requires. - Update
cli/src/registry.ts: bumpSUPPORTED_REGISTRY_VERSIONfrom<N>to<N+1>. - Ship in lockstep: one PR carrying schema + yaml + CLI bump. Vercel deploys the dashboard against the new yaml; users running the previous CLI globally will see
REGISTRY_VERSION_UNSUPPORTEDwith an upgrade hint on next read. - Open a decision doc:
docs/decisions/YYYY-MM-DD-registry-schema-v<N+1>.mdrecording the rationale + the migration plan for entries that need hand-fixing. - Tag a CLI release:
npm version majorincli/, push the tag. The upgrade hint inRegistryVersionErrorpoints users at npm.
Verification
Section titled “Verification”After the PR merges:
# Old CLI (one version behind):npx --package=@petrova/cli@latest-1 petrova status# Expected: REGISTRY_VERSION_UNSUPPORTED with upgrade hint.
# New CLI:npx --package=@petrova/cli@latest petrova status# Expected: clean output.Why this matters
Section titled “Why this matters”Without the gate, an old CLI reading a new registry produced an
opaque AJV error like "must be equal to constant". Operators
debugged that as a corrupt registry rather than a stale tool. The
explicit version check + upgrade hint short-circuits that loop.