mirror of
https://github.com/marcoallegretti/karapace.git
synced 2026-03-26 21:43:09 +00:00
e6e0f3dd6d
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.
98 lines
3 KiB
Markdown
98 lines
3 KiB
Markdown
# Contributing
|
|
|
|
## Setup
|
|
|
|
```bash
|
|
git clone https://github.com/marcoallegretti/karapace.git
|
|
cd karapace
|
|
cargo build
|
|
cargo test --workspace
|
|
```
|
|
|
|
## Verification
|
|
|
|
All of these must pass before submitting changes:
|
|
|
|
```bash
|
|
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`.
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# CLI only (default)
|
|
cargo build --release
|
|
|
|
# CLI + D-Bus service
|
|
cargo build --release --workspace
|
|
```
|
|
|
|
## Shell completions
|
|
|
|
```bash
|
|
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.
|