# Contributing — mgf-fed-web

`mgf-fed-web` is a Magogi Foundation sibling and **inherits the cross-project
engineering standards** from
[`mgf-common`](https://codeberg.org/magogi-admin/mgf-common).

## First read

1. [FEDERATION.md](FEDERATION.md) — the contract.
2. [SCOPE.md](SCOPE.md) — what belongs here (the **presentation layer only**; all read /
   sync / live logic lives in the `mgf-fedres` spine).
3. The authoritative design — the spec, brief, and dashboard wireframe in
   [`mgf-fedres/docs/planning/mgf-fed-web/`](https://codeberg.org/magogi-admin/mgf-fedres/src/branch/main/docs/planning/mgf-fed-web/),
   and the end-to-end [`PLAN.md`](https://codeberg.org/magogi-admin/mgf-fedres/src/branch/main/docs/planning/PLAN.md)
   (this tool is Phase B).

## Process

1. **Bug / feature:** file in [FEEDBACK.md](FEEDBACK.md).
2. **PR:** branch from main; run the gates locally:
   ```sh
   uv run --extra dev ruff check . && uv run --extra dev ruff format --check .
   uv run --extra dev mypy
   uv run --extra dev pytest --cov --cov-report=term-missing
   mgf-fed app-doctor --standards
   ```
3. **Stay a thin presentation layer** — the dashboard composes + displays; it never
   authors project state and never re-implements spine logic. Read / validate / sync /
   live all go through `mgf-fedres`; anything the web computes itself is tagged
   `derived`. New schema/sync/live behaviour belongs in the spine, not here.
4. **Honest-absence is non-negotiable** — a missing / stale / unreadable resource renders
   the explicit state + the one action that fixes it; never a blank, never
   stale-shown-as-current. The brand layer is **additive only** — never reduce the tool's
   power for styling.
5. **CHANGELOG.md:** add an `[Unreleased]` entry.
6. **CI is generated:** never hand-edit `.woodpecker.yml`; regenerate with
   `mgf-fed scaffold mgf-fed-web` (WF-13).
7. **Reviewer:** the federation owner (mgf-common maintainer).

## Release flow

Bump `pyproject.toml::version` + `mgf.fed_web.__version__` → build → test →
`twine check` → commit → tag `vX.Y.Z` → push tag (CI publishes to devpi) → regen the
registry (REL-13). Re-pin `mgf-fedres` / `mgf-brand-web` after the spine + brand kit
publish a new MINOR (this tool consumes both).
