Versioning and upgrades

What may change between releases, and how to upgrade.

Where this fits: Run and operate. The last page of the book.

The packages

Kervan follows semantic versioning from 0.1 on. Stable exports change incompatibly only in a new minor version while the version is 0.x, and the changelog says so. Experimental exports may change in any release. The programmatic API page lists which is which; anything not listed is internal, even when a deep import reaches it.

@kervan/core, @kervan/transport, @kervan/spec-runtime, kervan and create-kervan are released together with the same version.

The spec format

• specVersion: 1 changes only compatibly. A breaking format would become specVersion: 2, and Kervan would say which it needs.
• The editor schema for version 1 is served at https://getkervan.dev/schema/v1.json; a version 2 would get schema/v2.json, with v1.json left in place.
• Limits (HTTP_DEFAULTS, SPEC_LIMITS, SCHEMA_LIMITS) keep their names; their values may be tuned in minor releases.

Upgrading a project

Read the changelog first. Until the packages are on npm, a project made with pnpm try:new is upgraded by creating it again from a newer clone.