mirror of
https://github.com/marcoallegretti/karapace.git
synced 2026-03-26 21:43:09 +00:00
5306963cce
- docs/getting-started.md — install per distro, first use, common workflows - docs/architecture.md — 9-crate dependency graph, design decisions, data flow - docs/manifest-spec.md — manifest v1 specification - docs/lock-spec.md — lock file v2 specification - docs/store-spec.md — store format v2 specification - docs/hash-contract.md — two-phase identity hashing algorithm - docs/security-model.md — threat model, mount/device/env policy, privilege model - docs/cli-stability.md — 23 stable commands, exit codes, stability guarantees - docs/protocol-v1.md — remote protocol v1 draft - docs/layer-limitations-v1.md — phase 1 layer limitations - docs/api-reference.md — public API reference (Engine, D-Bus) - docs/versioning-policy.md — semantic versioning, deprecation policy - docs/verification.md — release artifact verification (SHA256, cosign, SBOM) - docs/e2e-testing.md — E2E test guide with distro-specific prerequisites - README.md — project overview, features, quick start, installation - CONTRIBUTING.md — development setup, architecture principles, code standards - CHANGELOG.md — full changelog for 0.1.0 and 2.0 hardening
66 lines
2.5 KiB
Markdown
66 lines
2.5 KiB
Markdown
# Karapace Versioning Policy
|
|
|
|
## Versioned Artifacts
|
|
|
|
Karapace versions three independent artifacts:
|
|
|
|
| Artifact | Current Version | Location |
|
|
|---|---|---|
|
|
| Manifest format | `1` | `manifest_version` field in manifest |
|
|
| Store layout | `2` | `store/version` file |
|
|
| DBus API | `1` | `org.karapace.Manager1` interface |
|
|
| Remote protocol | `v1-draft` | `X-Karapace-Protocol` header |
|
|
|
|
## Freeze Policies
|
|
|
|
### Store Format Freeze
|
|
|
|
- **Store layout v2 is frozen as of Karapace 1.0.**
|
|
- No breaking changes to the store directory layout, object naming scheme, or metadata JSON schema within 1.x releases.
|
|
- New optional fields may be added to metadata JSON with `#[serde(default)]`.
|
|
- Store v1 is not supported; Karapace 1.0+ rejects v1 stores with a clear error.
|
|
- If a future major version changes the store format, `karapace migrate` will be provided.
|
|
|
|
### Remote Protocol Freeze
|
|
|
|
- **Remote protocol v1 is currently `v1-draft`** and may change before Karapace 1.1.
|
|
- The protocol will be frozen (declared stable) in Karapace 1.1.
|
|
- After freeze: blob routes, registry format, and integrity checking are stable.
|
|
- New optional endpoints may be added without a version bump.
|
|
- Breaking changes require a protocol version bump and `X-Karapace-Protocol` negotiation.
|
|
|
|
## Compatibility Rules
|
|
|
|
### Manifest Format
|
|
|
|
- The `manifest_version` field is required and checked on parse.
|
|
- Only version `1` is supported in Karapace 0.1.
|
|
- Adding optional fields is a backward-compatible change (no version bump).
|
|
- Removing or renaming fields requires a version bump.
|
|
- Changing normalization or hashing behavior requires a version bump.
|
|
|
|
### Store Layout
|
|
|
|
- The store format version is stored in `store/version`.
|
|
- Karapace refuses to operate on a store with a different version.
|
|
- Adding new file types to the store is backward-compatible.
|
|
- Changing the object naming scheme or layout requires a version bump.
|
|
|
|
### DBus API
|
|
|
|
- The API version is returned by `ApiVersion()`.
|
|
- Adding new methods is backward-compatible.
|
|
- Changing method signatures requires a version bump.
|
|
- The interface name includes the major version (`Manager1`).
|
|
|
|
## Release Policy
|
|
|
|
- **Patch releases** (0.1.x): bug fixes only, no format changes.
|
|
- **Minor releases** (0.x.0): may add backward-compatible features.
|
|
- **Major releases** (x.0.0): may break backward compatibility with version bumps.
|
|
|
|
## Migration
|
|
|
|
- Karapace 0.1 does not support migration from other tools.
|
|
- Future versions may include `karapace migrate` for store upgrades.
|
|
- Manifest version migration is the user's responsibility.
|