Skip to content

Latest commit

 

History

History
224 lines (153 loc) · 17 KB

backward-compatibility.mdx

File metadata and controls

224 lines (153 loc) · 17 KB
title Backward compatibility policy for the spec
navTitle Backward Compatibility Policy
description Versioning strategy, deprecation timelines, breaking change policy, and migration support for ObjectStack

ObjectStack follows strict backward compatibility guarantees to ensure predictable upgrades and long-term stability for production deployments.

**Applies to:** `@objectstack/spec` and all packages in the ObjectStack ecosystem.

Versioning Strategy

**The 17.x minors ran under a launch-window override: a breaking change shipped as a MINOR release, not a MAJOR one.** Every published `@objectstack/*` package versions in lockstep, so the version number alone is not an upgrade-safety signal; read [Launch Window](#launch-window-minor-releases-can-contain-breaking-changes) at the end of this page before you upgrade across 17.x.

The v18 line has exited prerelease mode. While Changesets was in pre mode with the tag next, every release cut from main was the next 18.0.0-next.N on npm's next tag, and scripts/check-changeset-no-major.mjs stood aside in pre mode, so a pull request could declare a major bump. Changesets has exited pre mode, so the line's GA version is 18.0.0, which publishes to npm's latest tag, and the guard again fails a pull request that declares a major bump. See how a breaking stage lands on the v18 line.

After 18.0.0, a breaking change ships in a MINOR or a PATCH release. The maintainer's 2026-10-21 ruling (#25105) keeps the no-major guard and grades each change by the metadata protocol: a key, value or metadata type added, narrowed or given a new meaning takes MINOR, and every other change takes PATCH, breaking or not. A non-protocol breaking change (a REST response, a boot refusal, a CLI exit status, a removed runtime export) keeps its **BREAKING** banner and ships as a PATCH. 18.1.0, the first release under the rule, is a MINOR that carries 91 changesets declared breaking.

ObjectStack follows Semantic Versioning 2.0.0 (MAJOR.MINOR.PATCH). The table below describes what each component means; which version a breaking change ships in depends on the line, as the callout above says.

Version Component When Incremented Guarantee
MAJOR (X.0.0) Incompatible API changes May contain breaking changes
MINOR (0.X.0) New features — and, in the 17.x minors, breaking changes; after 18.0.0, any change to the metadata protocol (added, narrowed or semantic) Existing code may require migration; the release notes lead with what broke
PATCH (0.0.X) Bug fixes — and, after 18.0.0, every change that is not to the metadata protocol, breaking ones included Before 18.0.0, no behavior changes. After it, a PATCH can break a REST client, a boot or a script: read its release notes

SemVer Guarantees

  • Zod schemas are part of the public API surface. Adding optional properties is a MINOR change; removing or renaming properties is a breaking change, which the 17.x minors also shipped in a MINOR release.
  • TypeScript types inferred from Zod (z.infer<typeof Schema>) follow the same guarantees as their source schemas.
  • Helper functions (e.g., defineStack, defineStudioPlugin) maintain their call signatures within a MAJOR version.
  • Input formats — defineStack() accepts both array and map (Record) format for all named metadata collections. Both formats are guaranteed stable within a MAJOR version.
  • Enum values are append-only within a MAJOR version. Existing values are never removed or renamed in MINOR/PATCH releases.
  • Default values in schemas are not changed in MINOR/PATCH releases unless fixing a documented bug.

{/* os:check */}

// These imports are guaranteed stable within a MAJOR version
import { FieldSchema, ObjectSchema } from '@objectstack/spec/data';
import { defineStack } from '@objectstack/spec';
import { defineStudioPlugin } from '@objectstack/spec/studio';

Deprecation Timeline

When a feature, schema property, or API is deprecated, ObjectStack follows a structured wind-down process:

Phase 1: Deprecation Notice (MINOR release)

  • Feature is marked @deprecated in JSDoc comments
  • Zod schema property gets a .describe('DEPRECATED: ...') annotation
  • Runtime warning is emitted on first use (once per session)
  • Migration path is documented in the CHANGELOG

Phase 2: Migration Period

  • Deprecated feature continues to function without behavior changes
  • Documentation is updated with migration guides
  • Code examples are updated to use the replacement
  • CLI tooling may provide automated migration commands

Phase 3: Removal (MINOR release in 17.x, the next 18.0.0-next.N during the v18 prerelease)

  • Deprecated feature is removed from the schema
  • TypeScript types no longer include the property
  • Runtime code no longer supports the feature
  • The removal is called out in the release notes and marked **BREAKING** in the changeset

Shipped examples: 17.2.0 retired http_request_errors_total and sys_position.permissions under ADR-0049 enforce-or-remove, and 15.1.0 removed tenancy.strategy and tenancy.crossTenantAccess — all three in Minor Changes sections.

Timeline Summary

flowchart TD
    A["Deprecation notice — feature marked deprecated (warning emitted)"] --> B["Migration period — deprecated feature keeps working, no behavior change"]
    B --> C["Removal — retired at the boundary the ADR-0087 registry records (MINOR release in 17.x, the next 18.0.0-next.N during the v18 prerelease)"]
Loading
**No minimum survival window.** ObjectStack does not guarantee a deprecated feature survives for a fixed number of releases — [ADR-0049](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0049-no-unenforced-security-properties.md)'s dispositions for a flagged property are enforce, `experimental`, or remove, and none of them carries a dwell time. A deprecated feature is retired at the boundary the ADR-0087 registry records for it; in the 17.x minors that removal itself landed in a MINOR release, so a MINOR bump was where to expect a removal to arrive. During the v18 prerelease it landed in the next `18.0.0-next.N`.

Breaking Change Policy

What Constitutes a Breaking Change

Read the Breaking? column, not the version number: in the 17.x minors every row below — breaking or not — shipped in a MINOR or PATCH release, and during the v18 prerelease every row shipped in the next 18.0.0-next.N, so in neither case does the bump size tell you whether you have work to do.

Change Type Breaking? Version Impact (17.x minors)
Removing a schema property Yes MINOR
Renaming a schema property Yes MINOR
Changing a property from optional to required Yes MINOR
Narrowing a type (e.g., string → enum) Yes MINOR
Removing an enum value Yes MINOR
Changing default values Yes MINOR
Adding a new optional property No MINOR
Adding a new enum value No MINOR
Widening a type (e.g., enum → string) No MINOR
Adding a new schema/export No MINOR
Fixing validation to match documented behavior No PATCH
Fixing typos in descriptions No PATCH

Breaking Change Process

  1. RFC (Request for Comments) — Breaking changes are proposed as GitHub issues with the protocol:breaking label.
  2. Deprecation — The old behavior is deprecated in a MINOR release (see timeline above).
  3. Migration Guide — A detailed migration guide is published before the removal lands, in the release notes for the version that carries it.
  4. Release — In the 17.x minors the breaking change shipped in the next MINOR version, carrying a changeset entry marked **BREAKING**, and scripts/check-changeset-no-major.mjs failed a pull request that declared a major bump, because under lockstep one major would promote all 111 published packages. During the v18 prerelease it shipped in the next 18.0.0-next.N, because the guard stood aside in pre mode and a pull request could declare a major bump. Changesets has exited pre mode, so the guard fails a major bump again. See how a breaking stage lands on the v18 line.

Migration Support

Linting Your Project

The CLI's lint command checks your metadata for style and convention issues and surfaces them. Adding --fix prints the suggested fix for each issue (dry-run; it does not modify files):

# Check metadata for style and convention issues
os lint

# Show what could be auto-fixed (dry-run)
os lint --fix

# Scan your source for deprecated ObjectStack patterns
os doctor --scan-deprecations

# Compare two configs and detect breaking changes between versions
os diff <before> <after> --breaking-only
There is no `lint --deprecations` flag — deprecation scanning lives on `os doctor --scan-deprecations`. There is no `codemod` command either: to upgrade your metadata across MAJOR versions, run `os migrate meta` (see [Support Windows](#support-windows)), and use `os doctor --scan-deprecations`, `os diff`, and the CHANGELOG migration notes (below) for what it does not rewrite.

Migration Guides

Each MAJOR release includes:

  • CHANGELOG.md — Complete list of changes with migration notes
  • RELEASE_NOTES.md — High-level summary and upgrade instructions
  • Schema Diff — Use os diff <before> <after> to produce a machine-readable (--json) diff of breaking changes between two configs

Support Windows

Only the current MAJOR receives fixes. There is no maintenance line for an older MAJOR: compatibility across majors is carried by the protocol's conversion layer and migration chain (ADR-0087), not by patching old releases.

  • The current MAJOR — bug fixes and security patches ship in the next release cut from main. While the next MAJOR is in prerelease, every release cut from main is one of its prereleases on the pre-mode dist-tag (next on the v18 line), so a fix reaches latest only when that MAJOR goes GA.
  • The previous MAJOR, and every older one — receives no fixes, and no backport or maintenance release is promised. To take a fix, upgrade to the current MAJOR.
  • The conversion layer (ADR-0087 D2) — as the runtime loads your metadata, it converts the previous MAJOR's lossless changes (renames, alias removals, field moves) to the current shape and emits a deprecation notice per conversion, so those shapes keep loading after you move the runtime forward. It covers only the previous MAJOR and only lossless changes; os migrate meta carries everything else.
  • os migrate meta (ADR-0087 D3) — os migrate meta --from N replays the migration chain from the major your metadata was authored against (protocol 16 or later, the chain's floor) to the current one in a single pass, and lists the edits your source needs; with --write it writes the mechanical ones it can trace to one literal into your source files. It reads no database. os migrate meta --stored replays the same chain over one deployment's stored sys_metadata rows and, with --apply, rewrites the ones still carrying an older shape. See the CLI reference and Upgrading → The metadata app.
  • Testing a MAJOR before it reaches latest — scripts/check-changeset-no-major.mjs fails a pull request that declares a major bump outside Changesets pre mode and stands aside inside it, and a MAJOR declared in pre mode publishes only prereleases, on the pre-mode dist-tag, until pre mode exits; the v18 line used next (18.0.0-next.0 … 18.0.0-next.5) before 18.0.0. Install from that tag to run your app against a MAJOR before it becomes latest.

Spec Package Guarantees

The @objectstack/spec package provides additional stability guarantees:

Schema Stability

  • All Zod schemas are validated by comprehensive test suites
  • Schema changes require both Zod and JSON Schema output validation
  • Property additions must include .describe() annotations and .optional() or .default() markers

Export Stability

  • All public exports are listed in the package's index.ts barrel files
  • Removing an export is always a breaking change; the 17.x minors shipped it in a MINOR release, and during the v18 prerelease it shipped in the next 18.0.0-next.N
  • Internal modules (prefixed with _ or in internal/ directories) are not covered by SemVer guarantees

Runtime Behavior

  • Schema.parse() results are guaranteed consistent within a MAJOR version
  • Default values applied by .default() are stable within a MAJOR version
  • Validation error messages may change in MINOR/PATCH releases (do not rely on exact error text)

Launch Window: MINOR Releases Can Contain Breaking Changes

**The 17.x minors ran under this exception — read it before you upgrade across them.** Every published `@objectstack/*` package versions in **lockstep**, and in the 17.x minors a breaking change shipped as a **MINOR** release rather than burning a MAJOR, so those minors contain documented breaking changes. During the v18 prerelease every release cut from `main` was the next `18.0.0-next.N` on npm's `next` tag; Changesets has exited pre mode, so the line's GA version is `18.0.0`, which publishes to npm's `latest` tag. See [how a breaking stage lands on the v18 line](/docs/releases/v18#how-a-breaking-stage-lands-on-this-line).

Which surfaces this covers

All of them. It was not scoped to an experimental corner or a pre-release channel: all 111 packages published from this repository belong to a single Changesets fixed group, so they share one version number and one policy. No published surface was exempt.

The convention was enforced rather than informal — scripts/check-changeset-no-major.mjs failed a pull request that introduced a major bump, because under lockstep a single major on one package would promote the entire stack. During the v18 prerelease Changesets was in pre mode with the tag next and the guard stood aside, so a pull request on the v18 line could declare a major bump. Changesets has exited pre mode, and the guard fails a major bump again.

What this means for an upgrade

  • Do not read a MINOR bump as safe to take unattended. Read the release notes for the version you are moving to: they lead with breaking changes and carry the migration steps.
  • Pin exact versions instead of caret ranges if you cannot review each MINOR before it lands, and after 18.0.0 each PATCH as well.
  • Diff your own metadata across the upgrade with os diff <before> <after> --breaking-only.

MAJOR releases do still happen — 17.0.0 was cut precisely because its breaking density was too high to carry ^16.x consumers across on a caret range, and the v18 line is the next one — but in the 17.x minors an individual breaking change did not, on its own, force one.

When it stops applying

The tables and deprecation timeline above state this rule for the 17.x minors directly, beside what the v18 prerelease did. Classic SemVer — where a breaking change once again requires a MAJOR — is the settled form the project returns to once the launch window closes. It did not close at the 18.0.0 GA. The 2026-10-21 ruling (#25105) keeps the no-major guard on the v18 line and grades each change by the metadata protocol instead, so after 18.0.0 a breaking change ships in a MINOR when it narrows the metadata protocol and in a PATCH when it does not. For the 17.x minors, this section was the operative rule wherever any part of this page disagreed. For the 18.0.0-next.N prereleases, the operative rule is how a breaking stage lands on the v18 line. For the releases after 18.0.0, it is that ruling: read every release's notes, PATCH releases included, and pin exact versions.


Reporting Compatibility Issues

If you encounter an unintended breaking change:

  1. Check the CHANGELOG — Verify the change was not documented as intentional.
  2. Open an issue — File a GitHub issue describing the unintended change.
  3. Include a reproduction — Provide a minimal code sample showing the breakage.
  4. Reference the version — Specify the exact versions where behavior changed.