Versioning and releases
SemVer policy and how packages are published.
The project follows Semantic Versioning for the documented public API and npm export subpaths.
Pre-1.0
During 0.x, minor releases may include breaking changes needed to stabilize
lifecycle, errors, persistence, and adapters. Patch releases should stay
backward compatible. Breaking changes appear prominently in the changelog with a
migration path when practical.
Prereleases such as 0.2.0-beta.1 are for compatibility testing — pin exact
versions.
1.0 and later
| Kind | Meaning |
|---|---|
| patch | Compatible fixes and docs |
| minor | Compatible functionality |
| major | Incompatible API, behavior, or persistence |
Stable API includes documented exports and subpaths, request/response contracts, error classes and codes, ownership and lifecycle guarantees, and documented persisted-record compatibility.
Not public API: internal scheduler state, Redis key implementation beyond the compatibility policy, and undocumented adapter types.
Node support changes follow SemVer. Bun is compatibility-tested; it is not the supported UDP production runtime.
Release process
Maintainers:
- Bump version and changelog in a reviewed PR.
- Run typecheck, tests, build, and packed-consumer checks.
- Verify optional peers and Node/Bun compatibility.
- Tag
v<package-version>from the reviewed commit. - Let the tagged-release workflow verify the tag/version match and publish with npm trusted publishing / OIDC provenance.
- Publish GitHub release notes, including migrations and persistence notes.
Do not use a long-lived npm token when trusted publishing is available. Never replace a failed publish in place — ship a corrected version.
Security fixes may use a shorter private process, but still get a new version, provenance, changelog entry, and advisory after coordinated release.