Skip to main content

Contributing

:::info Status Implemented — process conventions, source: DEPLOY.md, CLAUDE.md. :::

Database changes​

  • Anything from the device-management module onward: write an Alembic migration (fastapi-backend/migrations/versions/), one op.execute(...) statement per call, no --autogenerate. downgrade() should raise NotImplementedError — schema stays additive; behavior reverts by environment-variable flag instead.
  • Do not add a new ensure_* function to core/db.py — that pattern is frozen for the ~17 tables that predate Alembic. New DDL is a migration.

Full detail: Backend Deployment — migrations.

Adding an API endpoint​

  1. Add the route in fastapi-backend/api/v1/endpoints/<domain>.py, with a response_model from schemas/<domain>.py.
  2. Register it in api/v1/api.py if it's a new router.
  3. The API Reference regenerates from the live OpenAPI spec — no manual doc update needed for the endpoint itself.

Adding a device-facing MQTT feature​

Read MQTT Protocol and the concept pages under Concepts first — identity, ownership, authorization, mosque binding, and playback entitlement are kept deliberately separate throughout this codebase; a change that conflates two of them is very likely wrong even if it works in the happy path.

Risky changes needing extra care​

  • Anything touching STREAM_AUTHZ_ENFORCE or FANOUT_V2 — these are staged production rollouts, not toggles to flip casually. Read Backend Deployment first.
  • Anything touching EMQX's authorization.cache setting or the ACL views — re-run scripts/emqx_acceptance.py against a throwaway broker.
  • Database credential/secret handling — never commit .env, emqx/certs/, or paste real secrets anywhere, including into documentation.

Documenting a decision​

If a change makes a real architectural trade-off (not just an implementation detail), add an entry under Design Decisions rather than only leaving it in a commit message or PR description — commit history isn't browsable the way this site is.

Running this documentation site locally​

See documentation-site/README.md for the full guide (adding a page, an ADR, updating the API reference, adding diagrams, deploying). In short:

cd documentation-site
npm install
npm start