Support and versioning policy

How @ltv/cwb is versioned, what it runs on, how APIs are deprecated, and which releases get fixes.

Versioning

• The package follows Semantic Versioning. Versions are computed by release-please from Conventional Commits.

• Before 1.0, the minor version is the breaking-change boundary:

  Release	May contain
  0.x.Y (patch)	Fixes and backward-compatible features
  0.X.0 (minor)	Breaking changes, listed in the changelog with a migration guide

• From 1.0, breaking changes only ship in a major release.

• Pin a pre-1.0 minor with a tilde range ("@ltv/cwb": "~0.2.0") so upgrades across breaking releases are deliberate.

• The public API is what @ltv/cwb and @ltv/cwb/datasources export (see the API reference), plus the documented behavior of createApp, the response envelope and the error handler. Files not re-exported from an entry point are internal and may change in any release.

Supported environments

Component	Supported	Notes
Runtime	Cloudflare Workers	Workers only: the package imports cloudflare:workers at load time. Node and Bun need a mock of that module (tests only)
compatibility_date	2026-01-14 or later	The date used by the library's own wrangler.jsonc and tests. Earlier dates are not tested
nodejs_compat flag	Recommended	The library imports no node:* modules, and a wrangler deploy --dry-run bundle built without the flag contains none. The tests and the example Worker run with nodejs_compat, so that is the verified configuration
hono (peer)	^4.13.0	Must resolve to a single copy in the app (instanceof HTTPException, context type augmentations)
chanfana (peer)	^3.4.0
zod (peer)	^4.4.3
drizzle-orm (optional peer)	>=0.45.0 <0.46.0	Only for @ltv/cwb/datasources
TypeScript (consumers)	5.9, 6.0, 7.0	Published .d.ts verified with each. Not a peer dependency. Consumers need Workers types (wrangler types) and skipLibCheck: true or @types/node (installation)
Bun (contributors)	1.4.x	Development only; CI uses 1.4.2 (contributing)

Widening a peer range is a minor or patch change. Narrowing one (dropping a supported version) is a breaking change.

Deprecation policy

1. Deprecate in a minor release. The API keeps working. It gets a JSDoc @deprecated tag naming the replacement, and the changelog lists it under deprecations.
2. Remove in the next breaking release:
   • before 1.0: the next minor release (for example, deprecated in 0.3.0, removed in 0.4.0 at the earliest);
   • from 1.0: the next major release.
3. Document the removal in a migration guide with before and after code, like the 0.2.0 migration guide.

Security fixes may skip the deprecation period when keeping the old behavior would leave users exposed; the changelog says so explicitly.

Security fixes

• Only the latest published minor receives fixes, security fixes included. Fixes ship as a patch release of that minor.
• There are no backports to older minors; upgrade using the migration guide.
• Report vulnerabilities privately as described in the security policy.