CALM Schema Governance Proposal

[rocketstack-matt]

CALM JSON Meta Schema Governance Process

1. Governance Overview

The CALM JSON Meta Schema must be governed through a structured process to ensure:

• Stability in released versions.
• Transparency and traceability of changes.
• Compatibility with CALM tooling (CLI, CALM Hub, Visualizer, etc.).
• Community involvement and review.
• Controlled adoption of schema updates in minor and major releases.

---

2. Change Management Process

a) Drafting New Schema Changes

• Proposed schema changes are made in the drafts/yyyy-MM folder (e.g., drafts/2025-02).
• Each draft version follows a YYYY-MM format, representing when it was created.
• Changes to draft schemas are allowed without restrictions to encourage iteration and innovation.

b) Change Proposals & Discussion

• Schema changes should be proposed via GitHub Issues and subsequent related Pull Requests (PRs) in the FINOS Architecture as Code monorepo.
• Each proposal must include:
  • Proposed Change: JSON Schema update details.
  • Impact Assessment: Expected impact on tools and existing schemas.
  • Test Coverage: How the change will be tested.

c) Review & Approval

• Each PR undergoes community review with at least:
  • One schema maintainer approval.
  • One tooling maintainer approval (to ensure compatibility).
  • A two-week comment period before merging.
• Schema maintainers may request:
  • Additional discussion via FINOS working group meetings.
  • Live demonstration of impact on tools (e.g., CLI, CALM Hub).

---

3. Release Process

a) Minor & Major Version Adoption

• Every six months, the maintainers select a draft version for potential adoption as a minor (v1.x) or major (vx.0) release.
• The selected draft undergoes full validation:
  • Schema linting and validation.
  • Compatibility testing with CALM tools.
  • Backward-compatibility checks.

b) Release Candidate Process

• Once validated, a Release Candidate (RC) (e.g., v1.2-rc1) is published in a dedicated releases/ folder.
• The community tests the RC for four weeks before finalization.
• If no major issues are found, the RC is promoted to an official minor or major release.

c) Final Release & Versioning

• Minor releases (e.g., v1.2) include backward-compatible improvements.
• Major releases (e.g., v2.0) introduce breaking changes and require migration guides.
• Each release is tagged and published in releases/.

---

4. Tooling Integration & Testing

• Before finalizing a schema release, it must pass tests against:
  • CALM CLI (schema validation, conversion, updates).
  • CALM Hub (storing, retrieving, and rendering architectures).
  • CALM Visualizer (ensuring new constructs render correctly).
• Maintainers ensure all tools are updated and compatible before the release date.
  • Where appropriate, tools that are to e deprecated rather than updated should be clearly documented.

---

5. Governance Roles

• Schema Maintainers: Approve schema changes, ensure consistency, enforce governance.
  • This group is maintained as a GitHub team.
• Tooling Maintainers: Validate compatibility with CLI, CALM Hub, and visualizer.
  • This group is based on the CODEOWNERS associated with the tool.
• Community Contributors: Propose, discuss, and review schema updates.

---

6. Communication & Transparency

• GitHub Issues & Discussions: All changes are tracked in GitHub issues.
• Working Group Meetings: Schema changes are discussed in the FINOS Architecture as Code working group.
• Release Notes: Each release includes a changelog documenting changes and migration steps.

---

Summary of Key Rules

Phase	Description	Governance Rules
Drafting	New changes in drafts/yyyy-MM	No restrictions, iterative changes allowed
Proposal	PRs submitted for changes	Requires schema & tooling approval
Selection	Draft chosen for release	Every 6 months, maintainers select a stable draft
Testing	Schema validated against all tools	4-week RC period for community testing
Final Release	Published as vX.Y	Fully tested, backward compatibility checked