Development Workflow

Development Workflow

Branching

Create a branch off main using one of these prefixes:

• feat/your-feature — new functionality
• fix/your-fix — bug fixes
• docs/your-doc — documentation changes

Pull Requests

• PRs require at least one review before merging into main
• PRs over 300 lines of code require review (per project rules)
• Fill out the PR checklist when opening
• All new functions must include JSDoc comments

JSDocumentation

Here's an example of how your JSDoc comments should look above functions

/**
 * Handles incoming event data from client applications.
 *
 * @async
 * @function handleIngest
 * @param {Request} request - The incoming HTTP request containing event data
 * @param {string} request.method - Must be POST
 * @param {Object} request.body - The JSON payload of the event
 * @param {string} request.body.event_id - Unique identifier for the event
 * @param {string} request.body.app_id - The application sending the event
 * @param {string} request.body.event_type - Type of event (e.g. "error", "feedback", "deploy")
 * @param {string} request.body.timestamp - ISO 8601 timestamp of when the event occurred
 * @returns {Response} 200 if the event was received successfully
 * @returns {Response} 400 if the request body is missing or malformed
 * @example
 * POST /ingest
 * {
 *   "event_id": "abc123",
 *   "app_id": "watchtower",
 *   "event_type": "error",
 *   "timestamp": "2026-05-04T12:00:00Z"
 * }
 */
async function handleIngest(request) {
  // handler logic here
}

---

Local dev loop

First time setup — run npm install inside each worker directory before running any commands:

cd workers/ingest && npm install
cd workers/api && npm install

Then from within each worker directory:

npm test
npm run lint

1. Make your changes
2. Run npm test to confirm tests pass
3. Run npm run lint to catch any lint errors
4. Run ./scripts/smoke.sh for end-to-end checks against a live worker

CI

On every PR, CI runs ESLint, unit tests, and a build check automatically. Don't merge if CI is red.