# Versioning

What can change between kogut versions, and which image tags to use.

kogut uses [Semantic Versioning](https://semver.org). Before 1.0, a minor version such
as 0.2 can change the configuration, and patch versions such as 0.1.2 fix bugs. Every
release in the [releases](https://github.com/piotrkowski/kogut/releases) and the
[changelog](https://github.com/piotrkowski/kogut/blob/main/CHANGELOG.md) starts with
**What to change**: the steps to take when you upgrade, or "Nothing.".

A key, feature, CLI command, or API field is removed or renamed only after at least one
earlier minor version deprecates it: the old form keeps working, the server logs a
warning when it is used, and the changelog lists it under "Deprecated".

Between minor versions, these can change:

- `kogut.toml` and environment variables
- The response shapes of the [HTTP API](https://docs.kogut.dev/reference/http-api/) under `/api/v1`
- The database schema. kogut saves a copy of the database before it migrates, and an
  older binary refuses a newer schema. See [Upgrading](https://docs.kogut.dev/installation/upgrading/).

Within a minor version, the [CLI](https://docs.kogut.dev/reference/cli/) keeps its exit codes and its
`--json` fields. New JSON fields can appear in any release.

A server accepts agents from the previous minor release for at least 30 days after it
ships. When a feature needs newer agents, **What to change** says so. Update the server
first, then the agents. See
[Agent compatibility](https://docs.kogut.dev/installation/upgrading/#agent-compatibility).

The `0.1` image tag tracks 0.1.x patches; a full tag such as `0.1.0` pins a release.
There is no `latest` tag.