Skip to content
Movement Mapping Tool

Adding a feature

Check what you’re allowed to change

Section titled “Check what you’re allowed to change”

Before you start, check .github/CODEOWNERS and CONTRIBUTOR_POLICY.md.

  • CONTRIBUTOR_POLICY.md lists locked paths: migrations, server functions and middleware, routing, infrastructure config, dependency manifests, the graph data model. It also lists open paths: presentational components, styles, copy, accessibility and these docs.
  • Branch protection on main requires a code owner’s approval.
  • A branch named design/* means the work is design-only, and stays on open paths.

If a change seems to need a locked path you don’t own, stop and flag it to an owner instead of building it.

The layers of a change

Section titled “The layers of a change”

Most features touch these, in this order:

  1. Schema. Add a migration in supabase/migrations/ (see Migrations). network rows carry map_id, never org_id. No foreign keys between schemas. Index the columns RLS policies use.
  2. Server function. Add or change it in apps/app/src/server/functions/, with authMiddleware or orgMiddleware and an authz helper (see Auth and permissions).
  3. Data. If it feeds the graph, map the results onto the shared GraphData type.
  4. UI. Node and connection data goes through the TanStack DB collections (see Editing internals). Everything else uses TanStack Query. New workspace UI has a set place to go (see Workspace UI).
  5. Docs. Update this site in the same PR.

Docs are part of the change

Section titled “Docs are part of the change”

A PR that changes what users see, or how the system works, isn’t finished without a docs update. The PR template has a checklist.

  • A user-facing change: update the pages under users/.
  • Architecture, data model, deployment or workflow: update the pages under developers/.
  • A new environment variable: update Environment variables and .env.example.
  • A schema change: update Data model.

Follow Writing docs. Rewrite what’s changed; don’t append.

Before opening a PR

Section titled “Before opening a PR”

Run pnpm check, pnpm typecheck and pnpm build. CI runs the same checks with a frozen-lockfile install. CI doesn’t run the tests, so run pnpm test yourself when you touch server code (see Testing). CI’s Socket.dev supply-chain scan is advisory: it runs only when its key is set, and never fails the build.

Shipping

Section titled “Shipping”

Merging to main:

  • applies your migrations to movement-mapping-dev
  • deploys the dev app (network-mapping-app-dev) and the docs site.

Production moves only when you publish a release:

Terminal window
pnpm release

That drafts a release with grouped notes and a list of pending migrations. Review it and publish. Publishing applies the migrations to movement-mapping-prod, then deploys the app. See Deployment.