Versioned API Change Contracts

When changing a user-facing interface (API/config/grammar or externally consumed resources), treat it as a versioned contract:

1) Classify change severity and reflect it in release artifacts

• For deprecations: include the “why” (what/which user scenarios are impacted) and what the supported alternative is.
• If you also ship compatibility work (e.g., supporting the new config “whenever possible”), add a separate fix/patch-level entry rather than burying it in the deprecation note.

2) Isolate breaking changes from releases you can’t roll back

• If behavior/grammar is breaking, do not ship additional new syntax in the same release unless you have an explicit, reversible plan.
• Prefer shipping only the currently agreed compatibility surface, and track additional syntax separately.

3) Explicitly version external interface/resource URLs

• For CDN/external loaders used by clients, include a major version (or equivalent) in the URL so updates don’t silently change runtime behavior.

Example patterns:

• Changeset structure (deprecation + patch/fix): ```md — ‘my-feature’: patch — fix: Support the htmlLabels config value whenever possible

‘my-feature’: minor — feat: Deprecate flowchart.htmlLabels in favor of root-level htmlLabels

- Staged syntax release (don’t mix breaking syntax):
```text
Release N: ship only `@{ ... }` syntax (no additional simplified grammar)
Release N+1: add simplified syntax under separate ticket/version

• Versioned CDN URL:

  // Prefer an URL that includes a major version segment
  fetch('https://cdn.example.com/mermaid@3/icons/icons.json')
  

Apply this standard to ensure clients get predictable behavior, deprecations are actionable (not vague), and breakage risk is contained through semantic change classification and explicit versioning.