153 lines
5.6 KiB
Markdown
153 lines
5.6 KiB
Markdown
# Versioning Policy
|
|
|
|
This document defines Miroir's backward-compatibility commitments and versioning practices.
|
|
|
|
## Overview
|
|
|
|
Miroir follows [Semantic Versioning](https://semver.org/):
|
|
- **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**:
|
|
```markdown
|
|
## [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](https://semver.org/)
|
|
- [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
|
|
- [Miroir Plan §12: Versioning commitments](/docs/plan/plan.md#versioning-commitments-from-v10)
|