Versioning Policy
beachcomber follows Semantic Versioning 2.0.0. This document defines what constitutes a breaking change across each public surface.
All versions before 1.0.0 are pre-release. Minor versions may include breaking changes during this period, but they will always be documented in the CHANGELOG.
Public Surfaces
Protocol (Unix socket wire format)
| Change | Version bump |
|---|---|
New operation (e.g., a new "op" value) | Minor |
| New optional field in response | Minor |
| Remove or rename an operation | Major |
| Change response field semantics | Major |
| Change wire encoding (e.g., away from NDJSON) | Major |
Config (config.toml)
| Change | Version bump |
|---|---|
| New config key with a default value | Minor |
| New config section with defaults | Minor |
| Remove or rename a config key | Major |
| Change the meaning of an existing value | Major |
| Change config file location or format | Major |
Built-in Providers
| Change | Version bump |
|---|---|
| New provider | Minor |
| New field on an existing provider | Minor |
| Remove a provider | Major |
| Remove a field from a provider | Major |
| Change a field's type or semantics | Major |
| Change a provider's default trigger strategy | Minor (documented) |
CLI (comb)
| Change | Version bump |
|---|---|
| New subcommand | Minor |
| New flag on an existing subcommand | Minor |
| Remove a subcommand | Major |
| Remove or rename a flag | Major |
| Change default output format | Major |
Client SDKs
Each SDK follows its own language ecosystem versioning. SDK versions are independent of the daemon version, but SDK releases will document which daemon protocol version they target.
Rust Library Crate (beachcomber-client)
Standard Rust API compatibility rules apply. Public API changes follow the Cargo SemVer reference.
Shared Library Provider C ABI
The C ABI documented in Provider Development §7 is a public binary interface. The three exported symbols — beachcomber_provider_metadata, beachcomber_provider_execute, beachcomber_provider_free — and their signatures are covered by the same stability guarantees as the wire protocol.
| Change | Version bump |
|---|---|
| Add a new optional exported symbol | Minor |
| Extend the metadata JSON schema with new optional fields | Minor |
| Change the signature of an exported symbol | Major |
| Change the ownership/free contract | Major |
| Change how the daemon locates and loads libraries | Major |
Libraries built against version X.Y of the ABI are expected to keep loading on any X.Z daemon without recompilation.
What Is Not a Public Surface
These may change in any release without a version bump:
- Log output format and messages
- Benchmark results and internal performance characteristics
- Internal module structure and private APIs
- Daemon process management details (PID file location, fork behavior)
- Script provider execution internals (as long as the config contract is maintained)