# Contributing — mgf-uitest-web

`mgf-uitest-web` 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. [FEDERATION.md](FEDERATION.md) — the contract (a pointer stub; canonical in
   mgf-standard per DOC-17).
2. [docs/standards/README.md](docs/standards/README.md) — the pointer to the
   inherited rule corpus at
   [mgf-standard/docs/standards/](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/).
3. [SCOPE.md](SCOPE.md) — what belongs here (a **black-box** browser harness; it
   never imports a console's own web stack).

## 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              |
| 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 the four green gates locally (the browser is
   needed for the suite — see [STARTHERE.md](STARTHERE.md) for the one-time
   `playwright install chromium` step):
   ```sh
   ruff check src tests && ruff format --check src tests
   mypy --strict src
   pytest --cov --cov-report=term-missing
   lint-imports
   ```
   `lint-imports` is not optional here: the `PR-01` import-linter contract in
   `pyproject.toml` is what mechanically pins the **black-box promise** — the
   harness MUST NOT import `fastapi` / `starlette` / `jinja2` or any console's
   own stack.
3. **CHANGELOG.md:** add an `[Unreleased]` entry per
   [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
4. **Public-API delta:** update [PUBLIC_API.md](PUBLIC_API.md)
   in the same PR; the pinned test gate will catch a missed entry.
5. **Reviewer:** the federation owner (mgf-common maintainer).

## Release flow

See [REL-* in the standards corpus](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/RELEASING.md).
Short version: bump `pyproject.toml::version` **and**
`src/mgf/uitest_web/__init__.py::__version__` (they MUST match, per **AP-13**) →
regen `PUBLIC_API.json` → build → test → `twine check` → commit → tag `vX.Y.Z` →
push tag → publish to the self-hosted **devpi** index (`magogi/prod`) — not PyPI.

## See also

- [STARTHERE.md](STARTHERE.md) — entry point
- [FEDERATION.md](FEDERATION.md) — the federation contract (feedback discipline)
- [mgf-common/CONTRIBUTING.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/CONTRIBUTING.md) — the canonical contributor guide
