versioning.mdx

title	Runtime service API versioning policy
navTitle	Runtime Service API Versioning
description	Stability labels and how to track runtime service API breaking changes.

Stability Labels

• stable: backward-compatible within the current major version.
• experimental: can change in minor versions; verify release notes before upgrades.

These two labels are the whole vocabulary. The same list is written out again as the chapter's Stability Legend, and scripts/check-runtime-services-index.mjs holds both legends — and every page's Stability bullet — to one definition, so the two lists cannot drift apart. Adding a label means extending that definition in the same change that says what it promises, in both places.

Breaking-Change Tracking

When a runtime service API changes in a breaking way:

1. Update the relevant page in this chapter.
2. Add a changeset entry under .changeset/ — changesets generates each package's CHANGELOG.md from these entries. (The root CHANGELOG.md is retained for historical entries and is not hand-edited.)
3. Record migration guidance and affected methods in the per-major release page under content/docs/releases/.

Current Matrix

Service	Stability
services.data	stable
services.sharing	stable
services.audit	experimental
services.queue	stable
services.email	stable
services.sms	stable
services.push	experimental
services.settings	stable
services.storage	stable