k7/CONTRIBUTING.md

Contributing to K7

Thanks for your interest in contributing.

K7 stays lean on purpose:

• Infra is a single Ansible playbook (src/k7/deploy/)
• CLI (Typer) and API (FastAPI) both wrap the same core module
• Tooling: uv, ruff, ty, pytest

Project direction

See ROADMAP.md for priorities. Near-term focus is the public release pipeline (PPA / GHCR / PyPI) after Katakate/k7d is published.

Repo layout

• src/k7/ — CLI, core, API, Ansible playbook
• src/k7_sdk/ — Python SDK (PyPI: k7-sdk)
• src/katakate/ — deprecated import shim → k7_sdk
• tests/ — unit + integration
• utils/ — helper scripts
• docs/BACKENDS.md — backend comparison (full docs: https://docs.katakate.org)

Packaging

• Root packaging (setup.py) builds the k7-sdk wheel for PyPI.
• CLI / playbook assets ship via the Debian package / install path, not the PyPI SDK package.

Code style

• Python: PEP 8, explicit types on public APIs, early returns
• Lint / format with Ruff via uv:

uv run ruff check src/ tests/
uv run ruff format src/ tests/
# or: make lint

Typecheck: make typecheck. Unit tests: make test.

Fast CLI iteration (dev.sh)

Avoid make build && make install while hacking the CLI:

./src/k7/cli/dev.sh --help
./src/k7/cli/dev.sh list
./src/k7/cli/dev.sh create --name test --image alpine:latest

Same flags as the installed k7 binary. For playbook / core / API changes, escalate: dev.sh → make test-integration-remote → make build && make install on a Linux node. Stack targets Linux x86; do not deploy or run the full stack on macOS ARM.

Releases

• Keep versions aligned in src/k7/__init__.py, src/k7_sdk/__init__.py, setup.py, pyproject.toml, and debian/changelog
• Tag vX.Y.Z once the public release pipeline is live
• See CHANGELOG.md

Reporting issues

Include steps, expected vs actual, logs, and environment (OS, arch, backend: kfd / kql / k7d, single- vs multi-node). Security reports: see SECURITY.md.