marcoallegretti/karapace
1
0
Fork 0
mirror of https://github.com/marcoallegretti/karapace.git synced 2026-03-26 21:43:09 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
karapace/docs/versioning-policy.md
Marco Allegretti 5306963cce docs: comprehensive public documentation 
- 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
2026-02-22 18:38:41 +01:00

2.5 KiB
Raw Blame History

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.