Versioning Policy¶

Kotobase follows Semantic Versioning

Semantic Versioning Summary¶

Version Increments

MAJOR.MINOR.PATCH

Segment	Incremented When
`MAJOR`	A breaking change is introduced
`MINOR`	A new backward-compatible functionality is added
`PATCH`	A backward-compatible bug fix is implemented

This page defines exactly what the Public API means, so you know what a version bump protects

What Is Public¶

The Public API, covered by this policy, is the surface re-exported from the top-level kotobase package and the documented command line

Public

Anything reachable from these and documented in the API Reference is something you can rely on

kotobase.__version__
The Kotobase class and its documented methods
All DTOs
The DatabaseNotFoundError and AudioDatabaseNotFoundError exceptions
All kotobase CLI command names and their documented options

What Is Not Public¶

Not Public

The following may change in any release, including patch releases, without being considered a breaking change

Internal Modules
models
repos
uow
connection
builder
terminal_output
The exact CLI output formatting and wording (Only the --json shape + the commands and options are stable)
The on-disk database file layout and any raw build artifacts

Database Schema¶

The compiled database is versioned independently of the package

Its format is recorded in the db_meta table as a schema_version, which you can see with kotobase db info

Public API + Database Versions

A database must match the schema that the installed kotobase API expects, therefore a schema_version change is ALWAYS considered a Breaking Change and released alongside a new MAJOR version (starting from 1.0.0)

Deprecations¶

After 1.0.0, when a Public API element is going to be removed, it is first deprecated

The deprecation is announced in the Changelog, the element keeps working for at least one minor release, and it emits a warning where practical before it is removed in a later release