---
title: Versions and stability
description: What a 1.x release of Hollware keeps working, what it does not promise, and how the repository holds it.
section: reference
order: 2
---

# 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.