Skip to content

Development & Deployment Practices

🛠️ Keep this practical: checklists and conventions, not theory. See Engineering Standards for repo/code conventions and Definition of Done, and Tools & Tech Stack for what's actually in use.

Development Environment Setup

Standard setup checklist for a new project or a new contributor:

  • Install required runtimes (Node/Python/etc.) for the project
  • Clone the repository and set up environment variables
  • Install dependencies
  • Run tests locally
  • Run the app/services locally

Conventions:

Area Standard
Repo structure Keep README and /docs updated as the project evolves
Env vars Use .env.example and document each variable
Secrets Use a secrets manager or password manager — never commit secrets (see Security & Data Handling)
Linting Enforce via CI, not just locally

Deployment Process

Principles: small, frequent releases; a rollback plan for every deployment; observability (logs/metrics/traces) before scale.

Generic deployment checklist:

  • Confirm the version/tag to deploy
  • Run the CI pipeline (tests + lint)
  • Review migrations, if any
  • Deploy to staging
  • Smoke test
  • Deploy to production
  • Monitor logs/metrics for 30–60 minutes
  • Write release notes

Integration Patterns

Common patterns for integrating with client or third-party systems:

  1. Webhook → queue → worker for reliability under load or downtime
  2. Idempotent APIs so retries are always safe
  3. Event logging for auditing and debugging

Integration checklist:

  • Confirm the source of truth (system of record)
  • Define API contracts (inputs/outputs)
  • Add retries with backoff
  • Add idempotency keys
  • Add logging (request ID + correlation ID)
  • Add monitoring and alerts for failures