Skip to content

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 exception hierarchy rooted at KotobaseError, re-exported from the top-level package
  • 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. The --json keys mirror the public DTO fields and keep Japanese text verbatim, but the exact serialization shape may change between 0.x minor releases
  • 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