CoordiationCSS
⌘ K
Menu
Docs/Core concepts/Compatibility

RELEASE POLICY · COMPLETE

Compatibility and deprecations

Know which public surfaces are stable, how long deprecated behavior remains available, which replacement is canonical, and which upgrade transform owns the change.

✓

The policy is implemented as data. Compiler results, upgrade tooling, documentation, and AI agents read the same stable deprecation IDs.

SEMANTIC VERSIONS

Promises grow with stability

The feature milestone and the stable release label remain separate decisions.

  1. 0.x

    Prerelease: incompatible changes still require documented deprecation when a compatibility path exists.

  2. 1.x

    Stable: documented APIs, class syntax, directives, CLI flags, schemas, and official adapter configuration remain compatible within the major.

  3. +

    Additive: utilities, variants, optional tools, and manifest fields may ship in minor releases.

  4. !

    Removal: deprecated stable behavior is removed only in an eligible major after its promised window.

01

Read the machine contract

compatibility.mjs
import {
  createCompatibilityManifest,
  deprecationRegistry,
} from "@coordiation/css";

console.log(createCompatibilityManifest({ prefix: "co-" }));

The manifest includes framework version, stable-policy start, runtime support, guarantees, prefix-aware replacement syntax, and every registered deprecation.

02

Inspect compiler diagnostics

Compile result
const result = compileCandidates(["co-flex", "hover:co--mt-4"]);

result.deprecations
// [{
//   code: "deprecated-candidate",
//   replacement: "hover:-co-mt-4"
// }]

Deprecated syntax remains accepted during its declared window. Diagnostics are returned as data and never written unexpectedly to application stdout.

03

Follow the full lifecycle

  1. Register a stable deprecation ID, introduction, earliest removal, replacement, and migration owner.
  2. Keep old behavior working and return a machine-readable warning.
  3. Ship a safe codemod when migration is mechanical.
  4. Document the release and migration guidance.
  5. Remove only in an eligible major release.

RELEASE GATE

45/45 is necessary, not sufficient

Feature implementation is complete, while the stable release still has operational gates.

  • Every public API, test, integration fixture, manifest, and guide must agree.
  • Supported-platform native builds and performance checks must pass for the release commit.
  • Native artifacts must be signed and attached through the release process.
  • Every breaking change needs migration guidance.
  • No prerelease version may be described as stable solely because the checklist reached 100%.
Previous← Plugin APINextRelease Check →