# Compatibility Policy

## Scope

This policy defines compatibility guarantees for the `kyrodb` Python package.

Public API scope:

- Objects exported from `kyrodb` (`src/kyrodb/__init__.py`)
- Documented behavior in `README.md` and docs under `docs/`

Internal scope (no compatibility guarantees):

- `kyrodb._generated.*` protobuf/gRPC modules
- Private symbols prefixed with `_`
- Internal adapter/converter modules and helper functions

## Current Phase: Alpha (`0.x`)

During `0.x`:

- Backward-incompatible API changes are allowed when needed for correctness, security, or design hardening.
- Any breaking change must be documented in release notes and migration notes before release.
- Public API removals must have an explicit replacement path.

## Beta / GA Target Policy

After beta cut:

- We follow semantic versioning for public API behavior.
- Breaking changes only in major releases.
- Minor releases may add functionality but must remain backward compatible.
- Patch releases are for bug fixes and must not break public API contracts.

## Release Gate Rule

No public API change is accepted unless all of the following are present in the same change set:

- Updated tests
- Updated docs
- Explicit migration note when behavior changes
