# Contributing to `mgf-standard`

## TL;DR

- The biggest contribution here is a **standards-rule change** — read the
  section below before touching `docs/standards/`.
- `uv sync --extra dev` to set up.
- Four gates must be green before opening a PR:
  ```bash
  uv run ruff check src tests scripts
  uv run ruff format --check src tests scripts
  uv run mypy --strict src/
  uv run pytest
  uv run lint-imports
  ```
- Vulnerabilities go to the private channel in [`SECURITY.md`](SECURITY.md),
  not the public issue tracker.

---

## Dev setup

```bash
git clone ssh://git@codeberg.org/magogi-admin/mgf-standard.git
cd mgf-standard
uv sync --extra dev
```

Verify the five gates are green on a clean checkout before making any change.

### Note on the test runner (TS-23 carve-out)

This repo does **not** dev-depend on `mgf-test-supervisor`. That edge would
create a registry dependency cycle (`mgf-standard` → `mgf-test-supervisor`
→ `mgf-common` → `mgf-standard`). The test surface here is trivial; we
run plain `pytest`. See `pyproject.toml` for the full rationale comment and
`docs/inprogress/MGF_STANDARDS_CONFORMANCE.md` for the CFM-04 decline record.

---

## Standards-rule changes (the primary contribution path)

Every change to [`docs/standards/`](docs/standards/) is a federation-wide
contract change — every `mgf-*` repo and every consumer conforms to these
rules.

**DOC-18 change-propagation requirement:** a standards change MUST update,
in the same commit:

1. The **README *Index of MUSTs*** (`docs/standards/README.md`) if a new MUST
   is added or an existing MUST is reworded.
2. Every **dependent named in the changed doc's Propagation header** — typically
   `mgf-common/docs/claude/CLAUDE.md` and whatever consumer guides reference
   the rule.

Skipping propagation leaves the federation in a split-brain state where the
rule and the docs that cite it disagree. This is the worst failure mode for the
standards-source role.

Additional bar for standards changes:

- Match the existing voice: dense, code-grounded, AS-IS callouts,
  cross-references.
- Bump the topic doc's version per the policy in `docs/standards/README.md`
  §Versioning (MAJOR = new MUST; MINOR = new SHOULD / template; PATCH =
  wording).
- Add the rule to the topic's mechanical-enforcement matrix, or write a
  justification for review-only.

---

## PR process

**Non-trivial work** (new rule MUST, new recipe, new dependency): open an issue
or add a `FEEDBACK.md` entry first. Let discussion converge before writing.
**Trivial work** (typo, wording, single-test bug fix): open the PR directly.

Branch from `main`. Branch name: `<topic>-<short-description>`.

Commits follow [Conventional Commits](https://www.conventionalcommits.org/):
`feat:`, `fix:`, `docs:`, `chore:`, `security:`. Subject ≤ 70 chars; body
explains *why*.

Every commit MUST end with both trailers (no exceptions — AG-03; setup in
[`docs/recipes/commit-signing.md`](docs/recipes/commit-signing.md)):

```
Signed-off-by: Bassam Alsanie <bassam@magogi.org>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
```

The `Signed-off-by` trailer is enforced automatically by the committed
`prepare-commit-msg` hook (it catches `git commit -m`, which bypasses the
`.gitmessage` template). Activate it once per clone:

```
git config core.hooksPath .githooks
```

The hook is idempotent and adds only the constant human signoff; you (or the
drafting agent) still add the `Co-Authored-By:` line naming the model.

PR description must cover: **What** / **Why** / **How** / **Test plan** /
**Standards compliance** (cite the rule ID) / **Breaking changes** (if any,
include the AP-12 four-part migration recipe in `CHANGELOG.md [Unreleased]`).

Maintainer-merge only. Every user-visible change gets a `CHANGELOG.md
[Unreleased]` entry before merge.

---

## Communication

| Channel | What it's for |
|---|---|
| Codeberg issues | Bug reports, rule proposals, public discussion |
| Codeberg PRs | Code + doc changes |
| Codeberg private security advisories | Vulnerability reports (per [`SECURITY.md`](SECURITY.md)) |
| [`FEEDBACK.md`](FEEDBACK.md) entries | Design decisions that need a permanent recorded rationale |

---

## License

By contributing, you agree that your contributions are licensed under the
project's [MIT License](LICENSE).
