Skip to main content

Versioning model

The SDK and the Delphi platform release on different cadences and ship from different repositories. The docs site keeps both in one place, but does not couple them — a platform docs version snaps the platform reference at a release tag; the SDK reference within it points at the SDK release compatible with that platform.

This page is for SDK consumers (so you know what to upgrade to) and docs maintainers (so you cut the right docs at the right time).

SemVer for the SDK​

The SDK follows SemVer:

  • Patch (0.1.3 → 0.1.4) — bug fixes only, no signature changes.
  • Minor (0.1.x → 0.2.0) — additive surface (new exports, new options), no removals or breaking changes.
  • Major (0.x → 1.0) — anything that needs caller changes. The changelog calls out every breaking change explicitly.

Compatibility matrix​

Every platform docs version has a Compatibility page with the matrix:

Platform versionRecommended SDKSupported SDK range
0.9.110.1.3>=0.1.0 <0.2.0

Reading the matrix:

  • Recommended SDK — what the platform release was tested with. New integrations should pin this exact version (or a ^-range that captures it).
  • Supported SDK range — what the platform release will interoperate with. SDKs outside this range may work, but are not validated against the platform.

When the SDK ships a new release that's still in-range for the current platform, the docs site is updated in-place (a new entry in the SDK changelog plus a refresh of the TypeDoc reference). The platform docs version doesn't move.

When the SDK ships a release that's outside the supported range for the current platform, the next platform release widens the range or pins to a new recommendation. Until then, the SDK changelog flags the gap.

How the docs are cut​

The site uses two independent Docusaurus instances:

  • Platform docs under / — versioned via pnpm docusaurus docs:version <X.Y.Z> on each platform release.
  • SDK docs under /sdk — same plugin family, a separate instance, with its own versions.json.

Each release cycle is small enough to run by hand or as a single CI step:

# Cut a new platform docs version
pnpm docusaurus docs:version 0.9.12

# Cut a new SDK docs version (different plugin id)
pnpm docusaurus docs:version --plugin-id sdk 0.1.4

After cutting, next continues to track development; older versions become read-only snapshots.

When to cut a new SDK docs version​

Cut a new SDK docs version when any of these is true:

  • A new SDK package version (any bump — patch, minor, or major).
  • A breaking change to the channel protocol or any public reference page.
  • A documentation rewrite large enough that consumers on the older SDK would be misled by reading the latest pages.

Otherwise, keep editing under next and let the changes flow to readers immediately.

When not to cut a new SDK docs version​

  • Typos and clarity fixes — apply to next. Older snapshots stay accurate enough.
  • TypeDoc regeneration only — that's a pnpm sdk:sync plus a PR, not a version cut.
  • Mid-cycle errata for a published platform version — see the soft-immutability rule below.

Soft immutability​

The working rule for both platform and SDK versioned snapshots:

Versioned docs may be corrected, but not advanced.

Corrections (typos, broken links, missing warnings, screenshot annotations) land directly in the versioned snapshot. Behavioural updates that describe new SDK or platform behaviour go into the next snapshot only, never into a published one.

See also​