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/CONTRIBUTING.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

3.2 KiB
Raw Blame History

Contributing to Karapace

Development Setup

# Clone and build
git clone https://github.com/marcoallegretti/karapace.git
cd karapace
cargo build

# Run tests
cargo test --workspace

# Full verification (must pass before submitting)
cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo build --release --workspace

Project Structure

crates/
  karapace-schema/    # Manifest parsing, normalization, lock file, identity hashing
  karapace-store/     # Content-addressable store, metadata, layers, GC, integrity
  karapace-runtime/   # Container runtime: images, sandbox, host integration, security
  karapace-core/      # Build engine, lifecycle state machine, drift control, concurrency
  karapace-remote/    # Remote store client, push/pull, registry
  karapace-server/    # Reference remote server (tiny_http)
  karapace-tui/       # Terminal UI (ratatui)
  karapace-cli/       # CLI interface (23 commands)
  karapace-dbus/      # D-Bus desktop integration (optional)
docs/                 # Public documentation and specifications
examples/             # Ready-to-use manifest examples
data/                 # systemd and D-Bus service files

Architecture Principles

Before implementing any feature, verify it aligns with these principles:

  1. Determinism first. Same manifest + lock = identical environment, always.
  2. No hidden mutable state. All state changes are explicit and tracked.
  3. No silent drift. Overlay changes are visible via diff and must be committed explicitly.
  4. No privilege escalation. Everything runs as the unprivileged user.
  5. Convenience must not break reproducibility. If there's a conflict, determinism wins.

See Architecture Overview for the full design.

Code Standards

  • Zero warnings: cargo clippy --workspace --all-targets -- -D warnings must pass.
  • Formatted: cargo fmt --all --check must pass.
  • No unwrap() in production code (test code is fine).
  • No TODO/FIXME/HACK in committed code.
  • All values interpolated into shell scripts must use shell_quote().
  • All mutating operations must hold a StoreLock.
  • All file writes must be atomic (use NamedTempFile + persist()).

Testing

  • All new features must include tests.
  • Run the full test suite: cargo test --workspace
  • Integration tests go in crates/karapace-core/tests/.
  • Unit tests go in the relevant module as #[cfg(test)] mod tests.

Submitting Changes

  1. Fork the repository.
  2. Create a feature branch from main.
  3. Make your changes, ensuring all verification checks pass.
  4. Submit a pull request with a clear description.

Building the D-Bus Service

The D-Bus service is not compiled by default:

# Core CLI only (default)
cargo build --release

# Include D-Bus service
cargo build --release --workspace

Generating Shell Completions

karapace completions bash > /etc/bash_completion.d/karapace
karapace completions zsh > /usr/share/zsh/site-functions/_karapace
karapace completions fish > ~/.config/fish/completions/karapace.fish

License

By contributing, you agree that your contributions will be licensed under the European Union Public Licence v1.2 (EUPL-1.2).