# Engineering Standards

This folder is **NOT a duplicate** of `mgf-standard/docs/standards/`.
The cross-project engineering standards (logging, configuration,
exceptions, design principles, security, testing, API design,
documentation, operability, deployment) live in `mgf-common`.
This project depends on those — pinned via
`mgf-common>=0.33,<0.34`. Read them on demand via
`mgf-common standards <topic>` or directly at
[`mgf-standard/docs/standards/`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/).

**Project shape:** **Federation sibling** of `mgf-common`
(per [`DOCUMENTATION.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/DOCUMENTATION.md) §2.0).

**Conformance target:** L2 — Observability-Native (Tier C) per
[`mgf-standard/docs/standards/README.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/README.md#conformance-levels-for-projects).
Inherited via the `mgf-common>=0.33,<0.34` dependency; the Django
adapters in this sibling preserve the parent's logging /
correlation / redaction guarantees through the request lifecycle.

---

## What lives in mgf-common (do not duplicate here)

Read these in `mgf-standard/docs/standards/` — they apply to
`mgf-django` as inherited rules:

| Doc | Covers |
|---|---|
| [`DESIGN_PRINCIPLES.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/DESIGN_PRINCIPLES.md) | DP-01..DP-13: layering, provider ABCs, frozen domain types, mypy strict, async ownership, UTC time, deterministic resource release. |
| [`ERROR_HANDLING.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/ERROR_HANDLING.md) | EH-01..EH-13: typed exception hierarchy, translation seams, top-level handlers, retry / backoff / circuit breaker. |
| [`LOGGING.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/LOGGING.md) | LG-01..LG-17: stdlib JSON, OTel correlation, redaction, sinks, async-context propagation. |
| [`CONFIGURATION.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/CONFIGURATION.md) | CF-01..CF-12: pydantic-settings precedence, schema versioning, atomic writes, vault separation. |
| [`SECURITY_STANDARD.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/SECURITY_STANDARD.md) | SC-01..SC-18: secrets, subprocess hygiene, redaction, vault, SBOM, dependency policy. |
| [`TESTING.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/TESTING.md) | TS-01..TS-21: layout, fixtures, mocks, property tests, GUI / async testing, perf benchmarks. |
| [`API_DESIGN.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/API_DESIGN.md) | AP-01..AP-15: `__all__` discipline, semver, deprecation cycle, py.typed, stability tiers. |
| [`RELEASING.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/RELEASING.md) | REL-01..REL-09: PyPI-is-the-contract, tag discipline, version-bump flow, FEEDBACK→SHIPPED closure. |
| [`WORKFLOWS.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/WORKFLOWS.md) + [`WORKFLOWS_PATTERNS.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/WORKFLOWS_PATTERNS.md) | WF-01..WF-12: four-gate CI baseline, tag-driven publish, secret-store discipline. |
| [`SCOPE.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/SCOPE.md) | What's in scope for mgf-common; cross-references for what siblings carry. |
| [`DOCUMENTATION.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/DOCUMENTATION.md) | DOC-01..DOC-12: seven-doc root contract, six-bucket hierarchy, priority-tracker shape, CLAUDE.md format. |
| [`OPERABILITY.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/OPERABILITY.md) | OP-01..OP-12: rich version visibility, doctor, config introspection, log access, bounded state. |
| [`DEPLOYMENT.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/DEPLOYMENT.md) | DEP-01..DEP-11: IaC, config-as-code, immutable artefacts, secrets, reversible deploys (applies to consumers, not to this library). |

Web-specific overlays live under
[`mgf-standard/docs/standards/web/`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/web/)
— consult these when deploying a Django (or FastAPI) consumer of
`mgf-django`.

---

## Project-specific standards

None. `mgf-django` is a thin Django-adapter sibling; its public
surface is five names (see [`PUBLIC_API.md`](../../PUBLIC_API.md))
and its responsibility is to bridge mgf-common's primitives into
Django's framework conventions. There are no project-specific
standards that extend the cornerstone.

If a Django-specific pattern emerges that warrants codification
(e.g., a `MgfDjangoRESTFrameworkAdapter`-style shape, or a
multi-app correlation rule), add a project-specific file under
this folder following the §2.0.4 Shape B pattern.

**Standing convention** (accepted from vm-vmanager-app's 2026-05-18
meta-feedback, FEEDBACK.md §3): any future mgf-django-authored rule
table MUST carry an applicability column — `web` / `service` /
`universal` — following mgf-common's DEP-* precedent, so non-web
consumers can mark whole namespaces N/A in one row.
