# Public API Stability
This document defines the `kafkit-client` public API policy for the initial
release.
## Public Surface
The supported public surface is the API exported from the `kafkit_client` crate
root and documented in the crate guides:
- Facade builders: `KafkaClient` and topic-scoped producer or consumer builders.
- Direct clients: `KafkaProducer`, `KafkaConsumer`, `KafkaShareConsumer`, and
`KafkaAdmin`.
- Configuration types: `ProducerConfig`, `ConsumerConfig`, `AdminConfig`,
`TlsConfig`, `SaslConfig`, and public configuration enums.
- Data model types used in public method signatures, such as records, headers,
offsets, topic partitions, group metadata, admin descriptions, ACLs, configs,
and share-consumer acknowledgement types.
- Public error types and the top-level `Error` classification helpers.
Examples and documentation should use the current names above. Older names that
are not exported from `kafkit_client` are not part of the API contract.
## Implementation Details
Internal modules, test helpers, protocol builders, scheduler/runtime state,
network connection internals, and generated Kafka protocol types are
implementation details unless they are re-exported from `kafkit_client` and
documented as public API.
Workspace crates used by applications, examples, bindings, or control-panel
packages may have their own release policy. They should not be treated as part
of the `kafkit-client` crate API unless documented by that package.
## SemVer Policy
Before `1.0`, minor releases may still tighten names, error variants, or
configuration details when needed for release readiness. Patch releases should
avoid breaking documented public APIs except for security or correctness fixes
that cannot be shipped compatibly.
After `1.0`, changes to documented public types, method signatures, enum
variants, or error classification behavior require a major version unless a
compatibility path is provided. New methods, new enum variants on
non-exhaustive-compatible types, and additional diagnostics may be added in
minor releases.
## Audit Checklist
Before a production release:
- `cargo doc --workspace --all-features --no-deps` must build without warnings.
- Public examples must compile under doctests or be marked `no_run` when they
require a live Kafka broker.
- Documentation must use current exported type names only.
- Unsupported Kafka APIs must not be implied by examples or release claims.
- Accidental internals should remain private or be clearly documented as lower
level extension points.