# For developers — contributing or designing alongside

> **Who you are.** You're contributing code or design input
> to `mgf-common`, OR you're designing a sibling Magogi
> library that needs to interop. You want the design rationale,
> the rule corpus, and the contribution flow.

## The mental model

`mgf-common` is the **cornerstone library** for Magogi. Three
of its design properties shape every contribution decision:

1. **API stability is gated by AP-11** — every public name
   ships `experimental`, gets promoted to `stable` after one
   full MINOR cycle without a 🔴 Blocker filed.
2. **Closed-box discipline (AP-14)** — module internals are
   private; the public surface is what `__all__` exports.
3. **Standards drive the bar, not aesthetics** — every PR
   asserts conformance to the relevant TS-* / EH-* / CF-* /
   LG-* / SC-* / AP-* / DP-* / REL-* / WF-* rule.

## Read first (in this order)

1. `mgf-fed standards README` — the master index for the rule
   corpus. Rule IDs are anchors; PR reviewers cite them.
2. [`docs/design/architecture.md`](../design/architecture.md)
   — high-level architecture (layering, dependency direction,
   the closed-box discipline).
3. [`docs/inprogress/strategic_review.md`](../inprogress/strategic_review.md)
   — explicit ambition + intentional limits; the scope your
   contribution should fit inside.
4. [`docs/design/multi_tenancy.md`](../design/multi_tenancy.md)
   — the most consequential design decision (hybrid module-
   global + opt-in `AppContext`); explains why bootstrap is
   shaped the way it is.
5. [`CONTRIBUTING.md`](../../CONTRIBUTING.md) — dev setup,
   the four green gates, the PR process.

## The standards corpus

The rule corpus (run `mgf-fed standards <TOPIC>` to read any
topic) is the canonical bar. 11 topic docs, organised as:

| Topic | CLI form | Rule prefix | What it gates |
|---|---|---|---|
| Design principles | `mgf-fed standards DESIGN_PRINCIPLES` | DP-* | Layering, separation, replaceability, testability, async, time |
| Error handling | `mgf-fed standards ERROR_HANDLING` | EH-* | Typed exception hierarchy, translation seams, top-level handlers |
| Logging | `mgf-fed standards LOGGING` | LG-* | Structured logs, JSON formatter, redaction, sinks, OTel correlation |
| Configuration | `mgf-fed standards CONFIGURATION` | CF-* | Layered config, schema versioning, framework-native carve-out |
| API design | `mgf-fed standards API_DESIGN` | AP-* | Stability tiers, naming, the closed-box discipline, `__all__` rules |
| Testing | `mgf-fed standards TESTING` | TS-* | The four-layer test pyramid, coverage gates, fixtures, marker registration |
| Security | `mgf-fed standards SECURITY_STANDARD` | SC-* | Secrets handling, redaction, dep audits, vulnerability process |
| Releasing | `mgf-fed standards RELEASING` | REL-* | Version bumps, cutover guides, consumer notification (REL-09) |
| Workflows | `mgf-fed standards WORKFLOWS` | WF-* | CI organisation, gating, branch conventions |
| Workflow patterns | `mgf-fed standards WORKFLOWS_PATTERNS` | (paste-ready) | Drop-in CI recipes |
| Common components | `mgf-fed standards COMMON_COMPONENTS` | (catalogue) | The shipped primitives and what each is for |

Plus per-kind subtree:

- `mgf-fed standards web/README` — web-domain narrative wrapper
  (when canonical rules apply, what's carved-out).
- `mgf-fed standards principles/non-adoption-is-valid` —
  cross-cutting principles.

## Design papers

Long-form design rationale at [`docs/design/`](../design/):

- [`architecture.md`](../design/architecture.md) — layering, dependency direction.
- [`strategic_review.md`](../inprogress/strategic_review.md) — ambition vs limits; the cornerstone framing.
- [`multi_tenancy.md`](../design/multi_tenancy.md) — the position paper on multi-consumer support.
- [`federation.md`](../design/federation.md) — the `mgf.*` sibling-package architecture.
- [`extraction_history.md`](../design/extraction_history.md) — historical context: how mgf-common emerged from vm-vmanager-app.

## The FEEDBACK relay

[`FEEDBACK.md`](../../FEEDBACK.md) is the canonical roadmap-
input mechanism. Three actor types: maintainer, consumer
agent, library user. The relay is documented in:

- [`FEEDBACK.md`](../../FEEDBACK.md) §1.4 — the entry template
  (Concern / Why it matters / Concrete evidence / Suggested
  shape with Approach A vs B framing).
- `mgf-fed standards RELEASING` REL-09 — the
  cutover-guide-as-notification mechanism for closed entries.
- [`docs/audience/ai-agents.md`](ai-agents.md) — the
  AI-side side of the relay.

## Contribution flow

```
  ↓ Open paper in FEEDBACK.md (§1.4 template)
  └─ Assign severity (🔴 / 🟡 / 🟢 / 💭)

  ↓ Maintainer triages: ACCEPT / DEFER / REJECT
  └─ Decision rationale recorded in entry

  ↓ For ACCEPT: implementation in topic-batched release
  └─ Tests pin contract (TS-07/08/09 plus the four-layer pyramid TS-19/20/21)

  ↓ Cutover guide drafted (REL-09)
  └─ Cross-references to relevant FEEDBACK.md entries

  ↓ Release: git tag, uv build, twine upload, PyPI smoke verify
  └─ Consumer notification paragraph relayed
```

## Contributing a new sibling library (mgf-*)

The `mgf.*` namespace package is implicit (PEP 420). Future
siblings (`mgf-apiprobe`, future) can land under
`mgf.<name>.*` from a separate repo. See
[`docs/design/federation.md`](../design/federation.md) for
the architecture, naming conventions, version-coupling
rules, and the lift-checklist (when a recipe earns promotion
to a primitive).

## Tools the maintainer uses

| Tool | Purpose |
|---|---|
| [`tools/generate_public_api_json.py`](../../tools/generate_public_api_json.py) | Regenerates `PUBLIC_API.json` from `__all__` introspection |
| [`tools/audit_consumers.py`](../../tools/audit_consumers.py) | Cross-references consumer projects' usage of `mgf.common.*` |
| [`tools/docs_explorer/serve.py`](../../tools/docs_explorer/serve.py) | Local web reader for docs (markdown rendering with cross-links) |
| `mgf-fed app-doctor` | Audits a consumer project's conformance against the standards |
| `mgf-fed standards <topic>` | Print a topic standard from the installed wheel |

## Running tests

The four-layer pyramid (TS-19/20/21):

```bash
pytest -m smoke              # post-install sanity, < 100 ms
pytest -m e2e                # bootstrap + chains
pytest -m integration        # cross-module
pytest                       # the unit base + everything
```

Per-layer coverage map: [`docs/inprogress/coverage.md`](../inprogress/coverage.md).

## What stays internal

[`docs/internal/`](../internal/) is for maintainer-only
artifacts. Currently:

- [`lift_checklist.md`](../internal/lift_checklist.md) —
  8-step recipe for lifting a component from a consumer
  project into `mgf-common` (or a sibling package).

Most other historical "internal" artifacts (`ARCHITECTURE.md`,
`STRATEGIC_REVIEW.md`, `EXTRACTION_HISTORY.md`,
`TEST_COVERAGE.md`, `BENCHMARKS.md`, `CI_STARTHERE.md`) were
promoted to public-facing locations in v0.25.0.
