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
97 lines
3.2 KiB
Markdown
97 lines
3.2 KiB
Markdown
# Contributing to Karapace
|
|
|
|
## Development Setup
|
|
|
|
```bash
|
|
# 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](docs/architecture.md) 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:
|
|
|
|
```bash
|
|
# Core CLI only (default)
|
|
cargo build --release
|
|
|
|
# Include D-Bus service
|
|
cargo build --release --workspace
|
|
```
|
|
|
|
## Generating Shell Completions
|
|
|
|
```bash
|
|
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).
|