Skip to content

bump registry schema

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.

ChangeBump?
New optional field with defaultNo
New required fieldYes — old CLIs would write entries missing it
Removed field referenced anywhereYes — old CLIs would read it as undefined
Renamed fieldYes
Tightened enum (smaller value set)Yes — old CLIs may write a now-invalid value
Loosened enum (additional values)No
  1. Update registry.schema.json: bump the version.const from <N> to <N+1>. Adjust any other schema changes you’re shipping in the same PR.
  2. Update registry.yaml: bump the top-level version: <N> to <N+1>. Hand-fix any entries the new schema requires.
  3. Update cli/src/registry.ts: bump SUPPORTED_REGISTRY_VERSION from <N> to <N+1>.
  4. 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_UNSUPPORTED with an upgrade hint on next read.
  5. Open a decision doc: docs/decisions/YYYY-MM-DD-registry-schema-v<N+1>.md recording the rationale + the migration plan for entries that need hand-fixing.
  6. Tag a CLI release: npm version major in cli/, push the tag. The upgrade hint in RegistryVersionError points users at npm.

After the PR merges:

Terminal window
# 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.

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.