Skip to content

Release Trains + Compatibility Contracts

Intent

Ship on predictable trains with semver, published packages, and compatibility promises.

Structure

Release trains + compatibility contracts are a release architecture: semver rules, published packages, changelogs, and migration guidance. Structurally it defines what stability means and how teams coordinate change with downstream implementers.

  • Release calendar: predictable cadence (monthly/quarterly) with defined cutoffs
  • SemVer contract: what counts as breaking/minor/patch for profiles, terminology, and tests
  • Package publication: repeatable build and publish steps so downstream installs are reliable
  • Changelog + migration: human-readable summaries plus actionable upgrade steps
  • Support window: how long old versions are supported and how deprecations are handled

Key Components

SemVer policy

  • Define major/minor/patch rules for IG packages
  • Document what counts as breaking
  • Apply policy consistently across artifacts
  • Require version bumps in PRs
  • Keep policy visible to implementers

Changelog

  • Maintain a human-readable changelog
  • Group changes by area (profiles, terminology, tests)
  • Include migration notes for breaking changes
  • Link to issues/PRs
  • Publish changelog with releases

Migration guide

  • Provide upgrade steps and code/FSH examples
  • Highlight removed/renamed elements and replacements
  • Include timelines and deprecation windows
  • Keep migration docs scoped and actionable
  • Validate migration guidance with downstream tests

Package publication

  • Publish packages to the appropriate registry
  • Ensure package metadata is correct and consistent
  • Verify downstream installs work
  • Keep release artifacts reproducible
  • Announce releases with links and summaries

Behavior

Ship predictably, evolve safely

Behavior is about making change boring: small batches, clear communication, and regression validation.

During development

  • Batch changes into trains; avoid unplanned breaking changes.
  • Keep CI green and ensure changes are covered by examples/tests.
  • Communicate early with implementers for high-impact changes.

At release

  • Publish package and changelog.
  • Publish migration guidance for breaking changes and deprecations.
  • Run cross-product smoke suite as a final gate.

Benefits

  • Plannable upgrades
  • Reduced surprises

Trade-offs

  • May delay some changes