Skip to content
RelKit
Esc
↑↓navigate↵open⌘Jpreview
On this page

Versioning and upgrades

What semantic versioning covers in RelKit, how deprecations and migrations work, and what has to be true before RelKit reaches 1.0.

RelKit is not at 1.0 yet. This page says what you can rely on today, what you can rely on from 1.0, how upgrades work, and what has to be true before 1.0 ships. All RelKit packages share one version.

What semantic versioning covers

From 1.0, Core features follow semantic versioning: an incompatible change ships only in a major release, new features ship in minor releases and fixes in patch releases. The Core and Labs page lists which features are Core.

Semantic versioning covers:

  • the documented APIs of Core packages, as listed in the API reference,
  • the relkit CLI’s commands and flags,
  • the RELKIT_* error codes and what each one means.

It does not cover Labs features, which can change or disappear in any release, or anything the documentation does not describe. Labs APIs carry the @experimental tag, and their docs pages show a Labs badge.

Before 1.0, minor releases can contain breaking changes. The breaking changes of the plan that leads to 1.0 ship together in one release, 0.9.0, preceded by a beta. After it, 0.x releases do not break Core without the deprecation window below.

Deprecations

A deprecated Core API keeps working for at least one minor release before it is removed. While it works, using it prints a warning that carries a RELKIT_DEPRECATED_* code, names the replacement and links to the code’s docs page. RelKit prints each deprecation warning once per process, so a deprecated call in a hot path does not flood your log.

For example, importing @relkit/app prints RELKIT_DEPRECATED_APP_PACKAGE, and passing Better Auth options to defineBetterAuthService prints RELKIT_DEPRECATED_BETTER_AUTH_OPTIONS. The error codes index lists every deprecation code.

Upgrades and migrations

Every breaking change ships with an automated migration and a migration note:

  1. The changelog entry for the change links a section of a migration guide, and a release check fails when a breaking change has no such link or no relkit migrate rule behind it.
  2. relkit migrate previews the changes it will make, applies them with --write, and undoes them with --rollback <receipt>.
  3. Changes the migration cannot apply are listed with their file and line, so you finish them by hand.

To upgrade, update the relkit and @relkit/* packages together, run relkit migrate, and run relkit check. The RelKit 0.9 migration guide walks through the one breaking release before 1.0. Each release’s notes are in the changelog.

What 1.0 means

RelKit reaches 1.0 when Core reaches 1.0, and not before all of these are true:

  • Core is complete. Every feature the maturity table lists as Core is implemented, documented and tested on every Tier 1 runtime: Bun, and Node 22 and 24.
  • The creation canary is green on Tier 1 runtimes. create-relkit creates every template on the latest Bun and on Node, and each project’s tests and dev server pass, every night.
  • The Railway newcomer test passes. A newcomer who follows the Railway guide from a new project deploys without steps missing from the guide, in under 15 minutes.
  • The metrics targets are met. create succeeds 100% of the time on the latest Bun for all templates; a newcomer reaches a first route in under 5 minutes; the HTTP test suite passes on Bun and Node; a save is serving again in under 1 second at p95 for a 100-function app; and relkit check peak memory is at or below tsc (benchmarks).

Until Core reaches 1.0, RelKit adds no new feature areas: bug fixes and hardening continue in both Core and Labs.

Target date

The target for 1.0 is the quarter after 0.9.0 ships. If a criterion above is not met by then, 1.0 waits for it and this page states the new date.