Versions and stability

Hollware follows semantic versioning from 1.0.0. A minor or a patch release keeps working everything an agent, a site, a script or a project built against an earlier 1.x; only a major release may break it. Every package of Hollware takes the same version, so @hollware/server@1.4.0 and @hollware/nuxt@1.4.0 go together.

What the promise covers

1. The MCP tools: their names, the scopes each asks for, their input and output schemas, and the shape of an error.
2. The read API at /v1: its paths, parameters and responses, as its OpenAPI document at /v1/openapi.json says.
3. The RPC entrypoint Hollware of a service binding: its methods and their signatures.
4. The events of webhooks: their kinds and fields, and how they are signed (verifyWebhook).
5. The CLI hollware: its commands and flags.
6. The exports of every published package: each name, value and type.
7. The migrations a release shipped: never changed or removed, only followed by new ones.

What a minor release may add

A new tool, path, method, command, flag, export or event kind; a new optional input; a new field in an answer or an event; a new value of an outcome or of an event's kind. Write your code so that it takes them in its stride: an outcome it does not know is an answer it does not act on, and an event kind it does not know is skipped.

What it does not cover

The admin's screens and its routes under /v1/admin, which only the admin calls; the wording of messages, fixes and descriptions; logs; and anything a package does not export. Read the code of an error, never its message.

How the repository keeps it

The public API lives in api/ of the repository, as the code makes it, and a test fails when the two differ, so every change of it shows in the change that makes it. From the first release candidate of 1.0 on, CI compares api/ with the newest release and fails on anything that breaks it: an input that gets stricter, an answer that loses a field, a scope a tool starts to ask for, a migration that changed.

Release candidates

1.0 comes through release candidates, 1.0.0-rc.N, on npm under the tag rc: npm install hollware@rc. A candidate keeps the promise of the one before it. Every release, candidates included, is published from CI with npm provenance.