ukmesh/docs/contributing.md

Contributing

Structural expectations

• routes should stay thin
• services own orchestration
• repositories own SQL
• worker RF math should stay separate from queue orchestration
• frontend map builders should stay separate from MapLibreMap.tsx

Repository hygiene

Do not commit:

• secrets
• credentials
• private database dumps
• personal or personally identifiable information
• operational traces containing sensitive infrastructure details
• artifacts that could be used for abuse or malicious access

If in doubt, keep it out of Git and add it to .gitignore.

DB changes

• backend/src/db/schema/base.sql represents a fresh database. Any schema change required by an existing deployment must be added as a new, ordered migration as well; do not edit a migration that may already be recorded.
• whole-history or destructive fixes go in explicit maintenance scripts, never migrations or startup
• apply pending migrations with docker compose run --rm db-migrate, not by running individual migration files or inserting migration-ledger rows by hand

Testing expectations

Before finishing a refactor or behavior change:

• use Node 20 and run cd backend && npm ci && npm run typecheck && npm test && npm run build
• run cd frontend && npm ci && npm test && npm run build && npm run test:e2e
• if worker code changed, build its image and run its tests there so GDAL and osgeo exactly match production
• run docker compose config --quiet
• rebuild affected containers and check http://localhost:3000/healthz