miroir/docs/versioning-policy.md

Versioning Policy

This document defines Miroir's backward-compatibility commitments and versioning practices.

Overview

Miroir follows Semantic Versioning:

• MAJOR: Incompatible changes
• MINOR: Backward-compatible functionality additions
• PATCH: Backward-compatible bug fixes

Starting with v1.0, Miroir provides the following backward-compatibility guarantees.

v1.0+ Commitments

Once Miroir reaches v1.0, the following surfaces are guaranteed backward compatibility within MINOR versions:

1. Meilisearch API Compatibility Layer

Commitment: No breaking changes in minor versions.

The /miroir/* API endpoints that proxy to Meilisearch will maintain compatibility with the Meilisearch API specification. Changes that would break existing clients require a MAJOR version bump.

Breaking changes include:

• Removing or renaming endpoints
• Changing request/response field names or types
• Modifying required query parameters
• Changing HTTP status codes for success/error conditions
• Altering authentication behavior

Non-breaking changes include:

• Adding optional request fields or query parameters
• Adding new response fields
• Adding new endpoints
• Performance improvements that preserve API semantics

2. miroir-ctl CLI Flags

Commitment: No incompatible changes in minor versions.

Command-line flags and subcommands will remain stable. Existing invocations and scripts using miroir-ctl must continue to work across MINOR versions.

Breaking changes include:

• Removing or renaming flags or subcommands
• Changing flag syntax (e.g., --flag to --different-flag)
• Inverting boolean flag semantics (e.g., --enabled defaulting to true vs false)
• Requiring additional mandatory flags for existing commands

Non-breaking changes include:

• Adding new optional flags
• Adding new subcommands
• Changing default values for optional flags (if the flag is not explicitly set)
• Improving help text and error messages

3. Config File Schema

Commitment: Backward-compatible in minor versions; new fields always optional with defaults.

Existing configuration files must remain valid across MINOR versions. New configuration options are always optional and provide sensible defaults when not specified.

Breaking changes include:

• Removing or renaming configuration keys
• Changing the type of an existing key
• Making a previously optional key required
• Changing the interpretation of a key's value incompatibly

Non-breaking changes include:

• Adding new optional keys with documented defaults
• Adding new sections to the config
• Relaxing validation constraints (e.g., expanding an enum)
• Deprecating keys (with warnings) before removal

4. Helm Chart Values Schema

Commitment: Backward-compatible in minor versions.

Existing values.yaml files must deploy successfully across MINOR versions. The chart maintains stability for GitOps and automated deployment workflows.

Breaking changes include:

• Removing or renaming values
• Changing the structure or nesting of values
• Making previously optional values required
• Changing default values in a way that breaks existing deployments

Non-breaking changes include:

• Adding new optional values with documented defaults
• Adding new nested structures under existing keys
• Introducing feature flags gated behind new optional values

Deprecation Policy

When a feature must be removed:

1. Mark as deprecated: Announce in the CHANGELOG with the [deprecated] tag
2. Provide migration path: Document how to update to the replacement
3. Wait one MINOR cycle: The deprecated feature remains functional for at least one full MINOR version
4. Remove in MAJOR or later MINOR: Removal is announced with [removed] in CHANGELOG

Example:

• v1.2: Feature X is marked [deprecated], replacement Y introduced
• v1.3: Feature X still works, warnings logged
• v1.4 or v2.0: Feature X removed, marked [removed]

For v1.x, removals that violate MINOR commitments require a MAJOR bump. However, features added in v1.2 may be removed in v1.4 if properly deprecated in v1.3.

Pre-1.0 Policy (v0.x)

Before v1.0, MINOR version bumps may include breaking changes.

This is explicitly permitted under SemVer for pre-1.0 software. However, Miroir will:

• Document all breaking changes in CHANGELOG.md
• Use the [breaking] tag for any breaking change
• Avoid breaking changes in PATCH versions unless necessary for security/critical fixes

Once v1.0 is released, this policy transitions to the v1.0+ commitments above.

CHANGELOG Tagging Convention

To make compatibility changes discoverable, CHANGELOG entries use these tags:

Tag	Meaning
[breaking]	Breaking change; MAJOR bump required (v1.x+)
[deprecated]	Feature marked for future removal
[removed]	Previously deprecated feature now removed

Example entry:

## [1.2.0] - 2026-06-01

### Changed
- [breaking] `/miroir/indexes` endpoint now returns `shard_count` instead of `replica_count`
- [deprecated] `--legacy-mode` flag in `miroir-ctl` (will be removed in v1.4)

Version Bump Decision Tree

Change affects:
├── API/CLI/config/Helm commitments (v1.x+)
│   ├── Breaking? → MAJOR bump
│   └── Non-breaking? → MINOR bump
├── Bug fix → PATCH bump
└── v0.x (pre-1.0)
    └── Any change may require MINOR bump; document with [breaking]

References

• Semantic Versioning 2.0.0
• Keep a Changelog
• Miroir Plan §12: Versioning commitments