# Contributing — mgf-vm-firecracker

`mgf-vm-firecracker` is a Magogi Foundation sibling and **inherits
the cross-project engineering standards** from
[`mgf-common`](https://codeberg.org/magogi-admin/mgf-common).
This file is short on purpose; the canonical contributor guide
is the federation contract.

## First read

1. [mgf-common/FEDERATION.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/FEDERATION.md) — the contract.
2. [mgf-standard/docs/standards/](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/) — the rule corpus.
3. `vm-vmanager-docs/developer/adding-an-adapter.md` — the playbook
   for building this adapter, and `contracts.md` §3/§4 — the
   `HypervisorBackend` + `StorageBackend` bar your code is measured
   against.

## Rule families (quick reference)

| Family | Covers                                                |
|--------|-------------------------------------------------------|
| AP-*   | API stability tiers, deprecation cycle                 |
| CF-*   | Layered config + env-var precedence                    |
| DEP-*  | Pin discipline, transitive caps                        |
| DOC-*  | Docs layout (universal-5 + sibling MUSTs)              |
| DP-*   | Design principles (frozen types, TZ-aware, …)          |
| EH-*   | Typed exception hierarchy                              |
| FB-*   | Feedback discipline (PAPER-NN flow)                    |
| LG-*   | Structured logging, redaction, audit emission          |
| REL-*  | Build → test → tag → push → upload order               |
| SC-*   | Atomic writes, redaction, secret handling (argv discipline) |
| TS-*   | Test discipline, four-gate CI                          |

## Process

1. **Bug / feature:** file in [FEEDBACK.md](FEEDBACK.md)
   (sibling-scoped) — or in
   [mgf-common/FEEDBACK.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/FEEDBACK.md)
   if cross-cutting (per DOC-13 / FB-04). If the friction is about
   the contracts upstream, file in `mgf-vm-core`'s `FEEDBACK.md`.
2. **PR:** branch from main; run the local gates:
   ```sh
   uv run ruff check src tests
   uv run mypy --strict src/
   uv run pytest -q -m "not integration"
   uv run lint-imports
   ```
   Integration tests (`-m integration`) require Firecracker +
   jailer binaries on PATH; opt in with `FIRECRACKER=1`.
3. **CHANGELOG.md:** add an `[Unreleased]` entry per
   [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
4. **Public-API delta:** the public surface is just
   `FirecrackerAdapter` + its constructor (the Protocol surface is
   owned by `mgf-vm-core`). Keep `src/mgf/vm/firecracker/__init__.py`
   re-exports in sync per AP-01.
5. **Reviewer:** the federation owner (mgf-common maintainer).

## Release flow

See [REL-* in mgf-common standards](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/RELEASING.md).
Short version: bump → build → test → `twine check` → commit →
tag → push tag → upload.

## See also

- [STARTHERE.md](STARTHERE.md) — entry point
- [README.md](README.md) — what this adapter is + scope boundaries
- [mgf-common/FEDERATION.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/FEDERATION.md) §7 — feedback discipline
- [mgf-common/CONTRIBUTING.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/CONTRIBUTING.md) — the canonical contributor guide
