Skip to content

BoardReadyOps Contract Versioning & Deprecation Policy

Status: Authoritative Policy Date: September 2026 Scope: CLI, GitHub Action, Report Outputs, Schemas, Cloud API, Plugin IPC

1. Scope & Purpose

BoardReadyOps operates across multiple integration boundaries: local developer workstations, GitHub Actions CI pipelines, hosted cloud control planes, and external manufacturing pipelines.

This document defines the strict versioning, compatibility, and deprecation policies governing all public contracts: - Core Entities: Finding, RunResult, HardwareImpactV1, ReadinessScore. - Report Formats: JSON findings, SARIF 2.1.0, Markdown summary/detail, HTML dashboard, JUnit XML, CycloneDX HBOM. - Schemas: schemas/*.schema.json. - Cloud Protocol & Wire Payloads: GitHub Action OIDC ingestion, runner protocol, REST API endpoints. - Plugin IPC & Extension API: @boardreadyops/plugin-sdk.

2. Semantic Versioning & Schema Lifecycle

BoardReadyOps adheres to Semantic Versioning (SemVer 2.0.0) across all binary and library releases.

Schema Versioning Model

Every machine-readable payload emitted by BoardReadyOps carries an explicit schemaVersion or version integer field (starting at 1).

                     ┌─────────────────────────┐
                     │     schemaVersion: N     │
                     └────────────┬────────────┘
                                  │
         ┌────────────────────────┴────────────────────────┐
         │ Non-breaking change (Additive)                  │ Breaking change (Major bump)
         ▼                                                 ▼
┌───────────────────────────────┐              ┌───────────────────────────────┐
│ • Add optional property       │              │ • Remove or rename property   │
│ • Add new enum value          │              │ • Change property type        │
│ • Loosen validation constraint│              │ • Stricter validation rules   │
│ ──> Keeps schemaVersion: N    │              │ ──> Bumps schemaVersion: N+1  │
└───────────────────────────────┘              └───────────────────────────────┘

Automated Enforcement

tests/snapshot/schemas.snapshot.test.ts snapshots the required-field set, additionalProperties strictness, enum/const values, and property structure of every schemas/*.schema.json (resolving $ref/$defs so a shared definition's shape is checked everywhere it is used). A shape change of any kind fails the snapshot and must be reviewed deliberately: update the snapshot (vitest -u) only after confirming the change is additive per the table below, or bump schemaVersion first if it is breaking.

Additive vs Breaking Changes

Change Type Classification Policy
Add optional field Non-breaking Allowed in minor/patch releases. Consumers must ignore unknown fields.
Add new rule ID or tag Non-breaking Allowed in minor/patch releases. Consumers must treat new rule IDs gracefully.
Add new report format Non-breaking Allowed in minor releases.
Remove/rename field Breaking Prohibited in minor releases. Requires major version bump + 180-day deprecation notice.
Change field type / semantics Breaking Prohibited in minor releases. Requires major version bump.
Make optional field required Breaking Prohibited in minor releases. Requires major version bump.

3. Backwards Compatibility Guarantees

  1. N-1 Schema Read Guarantee: The BoardReadyOps CLI and Cloud control plane guarantee the ability to parse and process RunResult and Finding structures generated by the previous major version (or legacy schemaVersion) without crashing or data corruption.
  2. Deterministic Fingerprints Across Releases: Finding fingerprints (Finding.fingerprint) are calculated from immutable semantic attributes (ruleId, resource.path, component reference, net name) using SHA-256. Code formatting or adjacent line modifications must never alter finding fingerprints.
  3. Report Contract Stability:
  4. boardreadyops.findings.json strictly adheres to schemas/findings.schema.json.
  5. boardreadyops.sarif.json conforms to OASIS SARIF v2.1.0 standard.
  6. build/hbom.json conforms to CycloneDX v1.6 Hardware SBOM specification.

4. Deprecation Lifecycle & Transition Timelines

When a field, CLI option, or contract endpoint is scheduled for retirement:

  1. Phase 1: Mark Deprecated (Minor release X.Y.0)
  2. Tag with @deprecated in TypeScript types.
  3. Emit a structured warning in boardreadyops doctor or stderr when the deprecated surface is used.
  4. Update documentation with the recommended migration path.
  5. Phase 2: Deprecation Window (Minimum 6 months / 180 days)
  6. The capability remains fully operational.
  7. CI and runtime continue to accept the legacy contract without breaking.
  8. Phase 3: Removal (Major release X+1.0.0)
  9. The deprecated capability is removed or rejected with an actionable migration error message.

5. Architectural Isolation Boundary

  • Local/CI Standalone Guarantee: The core CLI (boardreadyops), Action (action.yml), rules engine (src/rules/), and report generators (src/report/) must never import or depend on @boardreadyops/db, PostgreSQL drivers, or apps/web runtime modules.
  • Verification: Enforced continuously in CI via task verify:structure, scripts/verify-web-standalone.mjs, and scripts/verify-control-plane-worker-boundary.mjs.