Team Standards for Development

Owner(s): CrowdPM team | Last updated: 2026-03-08 | Status: Production

Team Standards for Development

Purpose

This page captures the minimum engineering standards contributors should follow when working on CrowdPM Platform.

1. Development environment standards

• Use the documented toolchain versions as closely as practical.
• Use the emulator-first workflow for normal feature work.
• Keep local secrets out of version control.
• Do not use the local/demo Firebase alias as a real deployment target.

2. Branch and change standards

• Make changes in reviewable increments.
• Keep infrastructure/config changes visible in the pull request description.
• When route names, claims, or env vars change, update docs in the same change set.

3. Verification standards before pushing

At minimum, run:

pnpm lint
pnpm -r build

Also run targeted tests when changing backend logic, frontend rendering behavior, or auth/pairing code.

If ingest behavior changes, also run the smoke test.

4. Smoke-test standard

The local smoke test is a primary regression check, not merely a presentation gimmick.

Contributors changing any of the following should run it:

• pairing flow;
• token or DPoP validation;
• ingest gateway;
• batch processor;
• map rendering path;
• dashboard smoke-test UI.

5. Documentation standards

Documentation is part of the deliverable.

When behavior changes, update the relevant layers:

1. source implementation;
2. README or /docs runbook;
3. wiki page(s).

Required especially for changes to:

• env variables;
• setup prerequisites;
• route families;
• role terminology;
• deployment process;
• demo flow.

6. Role terminology standard

Use the real role names consistently:

• guest
• authenticated user / device owner
• moderator
• super admin

Avoid replacing this with vague wording that hides actual permission boundaries.

7. Security and secret-handling standard

Never commit:

• .env.local
• .secret.local
• private keys
• downloaded service-account JSON files

Treat project targeting, secrets, and deployment context as deliberate release steps, not routine development defaults.

8. Operational caution standard

Before any demo or deploy:

• verify the environment being targeted;
• verify VITE_API_BASE and Firebase context;
• verify whether the audience expects local, demo, or production behavior;
• verify whether public/moderation boundaries are part of the presentation.

9. Handoff quality standard

A change is not truly complete if the next contributor cannot:

• run it locally;
• understand the role model;
• repeat the smoke test;
• locate the relevant docs.

Related pages

• Developer Setup & Project Conventions
• Demo Scripts
• Deployment Guide
• Wiki Editing & File Naming Notes