# Changelog & Versioning Policy

## Semantic Versioning

Demeter packages follow **SemVer** (`MAJOR.MINOR.PATCH`):

- **MAJOR** — backwards-incompatible API changes (removed/renamed endpoints,
  breaking response shape changes, dropped fields).
- **MINOR** — backwards-compatible additions (new endpoints, new optional
  fields, new libraries).
- **PATCH** — backwards-compatible bug fixes.

The REST API is additionally **path-versioned** at `/v1`. A breaking API change
ships under a new path prefix (`/v2`), not by mutating `/v1` — so existing
clients keep working. The OpenAPI spec's `info.version` reflects the package
version.

## Changelog from Conventional Commits

The changelog is derived from **Conventional Commit** messages, so writing good
commits _is_ writing the changelog:

| Commit type                                | Changelog section | SemVer bump |
| ------------------------------------------ | ----------------- | ----------- |
| `feat:`                                    | Features          | MINOR       |
| `fix:`                                     | Bug Fixes         | PATCH       |
| `perf:`                                    | Performance       | PATCH       |
| `docs:` / `test:` / `chore:` / `refactor:` | (usually omitted) | none        |
| `feat!:` or a `BREAKING CHANGE:` footer    | Breaking Changes  | MAJOR       |

Keep subjects lower-case and imperative; scope changes with `demeter` (or a
finer scope). A `BREAKING CHANGE:` footer documents the migration for consumers.

## Database versioning

Schema evolution is **forward-only** via numbered Drizzle migrations
(`drizzle/0000…`), applied with the expand→migrate→contract discipline so old
and new app versions coexist during a rollout. See the
[migration strategy](../operations/migration-strategy.md).

## Deprecation

When deprecating an endpoint or field:

1. Mark it deprecated in the OpenAPI schema (and document the replacement).
2. Keep it working for at least one MINOR cycle.
3. Remove it only in a MAJOR release (a new `/vN` for endpoints), with the
   removal noted under Breaking Changes.