mirror of
https://github.com/Katakate/k7.git
synced 2026-09-21 09:33:19 +00:00
G
72 lines
2.1 KiB
Markdown
72 lines
2.1 KiB
Markdown
# 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`](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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
./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`](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`](SECURITY.md).
|