mirror of https://github.com/marcoallegretti/karapace.git synced 2026-03-26 21:43:09 +00:00

Marco Allegretti e6e0f3dd6d docs: rewrite all documentation from source code

Delete 14 old docs files (AI-generated, riddled with Phase/M1/1.0
jargon, references to non-existent commands, stale CI snippets).

New documentation (6 files), written from repository source analysis:
- docs/architecture.md — crate graph, engine lifecycle, identity
  computation, runtime backends, store design, WAL, GC, unsafe blocks
- docs/cli-reference.md — all 23 commands with syntax, args, flags,
  exit codes, env vars, verified against crates/karapace-cli/src/main.rs
- docs/storage-format.md — directory layout, objects, layers, metadata,
  manifest format, lock file, WAL, atomic write contract
- docs/security-model.md — mount/device/env var policies with exact
  defaults from security.rs, trust assumptions, what is NOT protected
- docs/build-and-reproducibility.md — CI env vars, RUSTFLAGS, cargo
  profile, reproducibility verification, toolchain pinning
- docs/contributing.md — setup, verification, project layout, code
  standards, testing, CI workflows

README.md rewritten: concise, no marketing language, prerequisites
first, usage example, command table, limitations section.

CONTRIBUTING.md now points to docs/contributing.md.
CHANGELOG.md cleaned: removed M1-M8 labels, Phase refs, stale counts.

2026-02-23 01:25:07 +01:00

3 KiB

Raw Blame History

Contributing

Setup

git clone https://github.com/marcoallegretti/karapace.git
cd karapace
cargo build
cargo test --workspace

Verification

All of these must pass before submitting changes:

cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo build --release --workspace

Project layout

crates/
  karapace-schema/    Manifest parsing, normalization, lock file, identity
  karapace-store/     Content-addressable store, metadata, layers, WAL, GC
  karapace-runtime/   Container backends, images, sandbox, security policy
  karapace-core/      Engine: lifecycle orchestration, drift, concurrency
  karapace-cli/       CLI binary (23 commands)
  karapace-dbus/      D-Bus service (optional, not in default-members)
  karapace-tui/       Terminal UI (optional, not in default-members)
  karapace-remote/    Remote store client, push/pull, registry
  karapace-server/    Reference HTTP server for remote store
docs/                 Public documentation
docu_dev/             Internal development notes (not shipped)
data/                 systemd and D-Bus service files

default-members in Cargo.toml: schema, store, runtime, core, cli, server. The D-Bus service and TUI are opt-in.

Code standards

cargo clippy -- -D warnings — zero warnings.
cargo fmt — enforced.
No unwrap() in production src/ code. Tests are fine.
All values interpolated into shell commands must use shell_quote().
All mutating operations must hold a StoreLock.
All file writes must be atomic (NamedTempFile + persist()).

Testing

Unit tests: #[cfg(test)] mod tests in the relevant module.
Integration tests: crates/karapace-core/tests/.
E2E tests: crates/karapace-core/tests/e2e.rs — #[ignore], require user namespaces and fuse-overlayfs.

# Unit + integration tests
cargo test --workspace

# E2E tests (requires Linux with user namespaces)
cargo test --test e2e -- --ignored --test-threads=1

CI

Three workflows in .github/workflows/:

Workflow	File	What it checks
CI	`ci.yml`	fmt, clippy, tests (Ubuntu + Fedora), E2E, ENOSPC, release builds, reproducibility, smoke tests, lockfile, cargo-deny
Release	`release.yml`	Builds release binaries, signs with cosign, generates SBOM and provenance
Supply Chain	`supply-chain-test.yml`	Tamper detection, signature verification, adversarial injection tests

The ci-contract job in ci.yml verifies that all required jobs are present. See CI_CONTRACT.md.

Building the D-Bus service

# CLI only (default)
cargo build --release

# CLI + D-Bus service
cargo build --release --workspace

Shell completions

karapace completions bash > ~/.local/share/bash-completion/completions/karapace
karapace completions zsh > ~/.local/share/zsh/site-functions/_karapace
karapace completions fish > ~/.config/fish/completions/karapace.fish

License

Contributions are licensed under EUPL-1.2.

3 KiB Raw Blame History