# Contributing — mgf-logship

`mgf-logship` 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.

## 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 (uniform baseline + 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          |
| OB-*   | Observability — the canonical LogRecord wire           |
| REL-*  | Build → test → tag → push → upload order               |
| SC-*   | Atomic writes, redaction, secret handling              |
| 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).
2. **PR:** branch from main; run four-gate CI locally:
   ```sh
   .venv/bin/python -m ruff check src/ tests/
   .venv/bin/python -m mypy --strict src/
   .venv/bin/python -m pytest
   .venv/bin/python -m coverage report
   ```
3. **CHANGELOG.md:** add an `[Unreleased]` entry per
   [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
4. **Wire-protocol surface:** the versioned shipping wire protocol is
   the seam every collector + cross-language client builds on. Treat a
   change to it as an OB-/LG-governed contract change — bump the
   protocol version, flag it in the PR and CHANGELOG, update
   [DEPS.md](DEPS.md) §2 if the blast-radius shifts, and keep the
   handler **fail-open** (shipping must never break the host app).
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
- [DEPS.md](DEPS.md) — what we depend on + who depends on us
- [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
