Build it

A complete playbook for partner-api, the service behind Mangrove's Partner app: four files you can copy, a ruleset that enforces the important parts, and a script that measures lead time and deploys. Replace your-org and team names with yours. The core of the lead-time calculation is also a Practice exercise you can run in your browser.

1. Write CONTRIBUTING.md

   GitHub links to this file when someone opens an issue or PR, and shows it as a "Contributing" tab on the repo page. Put it in the repo root or .github/. Keep it to one screen of rules; link out for detail.

   MarkdownCopy

   # Contributing to partner-api
   
   This is how we work. If something here is wrong or slows you down, open a PR to change it.
   
   ## Your first day
   1. Get access: GitHub team `partner-team`, the staging VPN, and the team chat channel.
   2. `git clone git@github.com:your-org/partner-api.git && cd partner-api`
   3. `nvm use` (Node version from `.nvmrc`), then `npm ci`, then `cp .env.example .env`
   4. `npm run check` must pass. If it does not, tell us: that is a bug in this guide.
   5. Pick an issue labelled `good first issue` and open a draft PR before lunch.
   
   ## Branches
   - `main` is always releasable. Nobody pushes to it directly; the ruleset blocks it.
   - Branch from `main`: `feat/123-short-name`, `fix/123-short-name`, `chore/short-name`.
   - Delete the branch after merge (GitHub does it for you).
   
   ## Commits
   - Conventional Commits: `feat(api): add stock endpoint`, `fix(pos): round VAT in cents`.
   - Small and focused. The squash commit on `main` is the PR title, so make the title good.
   
   ## Pull requests
   - Aim for under 400 changed lines. Split bigger work behind a feature flag.
   - Fill in the template. Link the issue with `Closes #123`.
   - Open as draft early; mark ready when CI is green.
   
   ## Reviews
   - First response within one working day (Monday to Friday). Small PRs first.
   - One approval from a code owner. Two for anything under `src/payments/` or `prisma/`.
   - "Request changes" means it must change; "Comment" means a suggestion. Say which.
   - The author resolves threads and merges.
   
   ## Definition of done
   - [ ] Acceptance criteria in the issue are met
   - [ ] Tests added or updated; `npm run check` passes in CI
   - [ ] Database migration is backwards compatible (expand, then contract)
   - [ ] Logs and errors make sense to the on-call person
   - [ ] README, API docs or `.env.example` updated if behaviour or config changed
   - [ ] Product owner has seen it on staging (screenshots or a link in the PR)
   
   ## Releases and versions
   - Release every Tuesday after lunch: tag `vX.Y.0` on `main`. The release workflow deploys.
   - Semantic versioning: breaking API change = major, new feature = minor, fix = patch.
   - `CHANGELOG.md` is updated in the release PR from the merged PR titles.
   
   ## Hotfixes
   1. Open an issue labelled `incident` with what users see.
   2. Branch `fix/123-...` from `main`, write a failing test, fix, PR marked `hotfix`.
   3. One approval is enough; CI is still required.
   4. Tag `vX.Y.Z+1` straight after merge. Post the release link in the team channel.
   5. Within 3 working days: a short blameless note on the issue (cause, fix, prevention).

2. Add the PR template

   Saved as .github/pull_request_template.md, it fills every new PR description (Pull requests and code review). The "Risk" boxes tell reviewers, and you, where to look hardest.

   MarkdownCopy

   ## What and why
   <!-- One or two sentences. Link the issue: Closes #123 -->
   
   ## How to test
   <!-- Steps a reviewer can follow on staging or locally -->
   
   ## Screenshots or API examples
   <!-- For UI changes: before and after. For API changes: a request and response -->
   
   ## Risk
   - [ ] Database migration
   - [ ] Changes money, stock or prices
   - [ ] Touches login, permissions or secrets
   - [ ] Needs a feature flag or a config change on deploy
   
   ## Checklist
   - [ ] Tests added or updated
   - [ ] Under 400 changed lines, or explained why not
   - [ ] Docs or `.env.example` updated if needed

3. Add CODEOWNERS

   Save as .github/CODEOWNERS. Owners must be people or teams with write access. Because the last match wins, a change under src/payments/ goes to the leads team, and everything else to the whole team. The /.github/ line protects the workflows, the rules and this file itself.

   OutputCopy

   # .github/CODEOWNERS: who is asked to review what. The LAST matching line wins.
   *                     @your-org/partner-team
   /src/payments/        @your-org/partner-leads
   /prisma/              @your-org/partner-leads
   /.github/             @your-org/partner-leads
   /docs/                @your-org/partner-team @your-org/product

4. Enforce the rules with rulesets

   Keep the ruleset JSON in the repo, under .github/rulesets/, so changes to the rules are reviewed like code. The branch ruleset requires a PR, one approval from a code owner, approval of the latest push by someone other than its author, resolved threads, squash merges and green CI. A second ruleset stops release tags being moved or deleted, so v2.4.1 always means the same code. Both files validated against GitHub's published REST API schema.

   main.jsonrelease-tags.json

   JSONCopy

   {
     "name": "main: reviewed, green, squashed",
     "target": "branch",
     "enforcement": "active",
     "conditions": { "ref_name": { "include": ["~DEFAULT_BRANCH"], "exclude": [] } },
     "rules": [
       { "type": "deletion" },
       { "type": "non_fast_forward" },
       { "type": "pull_request", "parameters": {
           "required_approving_review_count": 1,
           "require_code_owner_review": true,
           "dismiss_stale_reviews_on_push": true,
           "require_last_push_approval": true,
           "required_review_thread_resolution": true,
           "allowed_merge_methods": ["squash"] } },
       { "type": "required_status_checks", "parameters": {
           "strict_required_status_checks_policy": true,
           "required_status_checks": [ { "context": "check (22)" }, { "context": "check (24)" } ] } }
     ]
   }

   TerminalCopy

   gh api repos/{owner}/{repo}/rulesets --method POST --input .github/rulesets/main.json
   gh api repos/{owner}/{repo}/rulesets --method POST --input .github/rulesets/release-tags.json
   gh api repos/{owner}/{repo}/rulesets --jq '.[] | "\(.id)  \(.name)  \(.enforcement)"'

   On GitHub (we could not run this from here): each POST returns the created ruleset with its id, and the last command lists both. To change a rule later, edit the file in a PR and apply it with gh api repos/{owner}/{repo}/rulesets/ID --method PUT --input .... The two status check names must match your CI job names exactly; with a matrix they are check (22) and check (24). If a hotfix ever needs someone to bypass the rules, add that person or team under bypass_actors deliberately, and review the bypass log.

5. Measure lead time and deploys with a script

   This script uses gh, so it runs with your existing login and permissions. It finds PRs merged into main in the last N days with one GraphQL search (paginated, 100 at a time), lists the releases in the same window, and works out three lead times. "First commit to released" is the DORA change lead time; the other two show where the time goes.

   JavaScriptCopy

   // scripts/lead-times.mjs: lead time and deploys for the last N days, from GitHub data.
   // Usage, inside the repo with gh logged in:  node scripts/lead-times.mjs 30
   import { execFileSync } from 'node:child_process';
   
   const days = Number(process.argv[2] ?? 30);
   const since = new Date(Date.now() - days * 864e5).toISOString().slice(0, 10);
   const gh = (...args) => JSON.parse(execFileSync('gh', args, { encoding: 'utf8', maxBuffer: 64e6 }));
   
   const repo = gh('repo', 'view', '--json', 'nameWithOwner').nameWithOwner;
   const query = `query($q: String!, $endCursor: String) {
     search(query: $q, type: ISSUE, first: 100, after: $endCursor) {
       nodes { ... on PullRequest { number createdAt mergedAt additions deletions
         commits(first: 1) { nodes { commit { authoredDate } } } } }
       pageInfo { hasNextPage endCursor } } }`;
   const prs = gh('api', 'graphql', '--paginate', '--slurp', '-f', `query=${query}`,
     '-f', `q=repo:${repo} is:pr is:merged base:main merged:>=${since}`).flatMap((p) => p.data.search.nodes);
   const releases = gh('release', 'list', '--limit', '200', '--json', 'tagName,publishedAt')
     .filter((r) => r.publishedAt >= since).toSorted((a, b) => a.publishedAt.localeCompare(b.publishedAt));
   
   const hours = (a, b) => (new Date(b) - new Date(a)) / 36e5;
   const rows = prs.map((pr) => {
     const firstCommit = pr.commits.nodes[0].commit.authoredDate;
     const shipped = releases.find((r) => r.publishedAt >= pr.mergedAt);    // first release after the merge
     return { number: pr.number, size: pr.additions + pr.deletions, review: hours(pr.createdAt, pr.mergedAt),
       toMerge: hours(firstCommit, pr.mergedAt), toProd: shipped ? hours(firstCommit, shipped.publishedAt) : null };
   });
   
   const pct = (xs, p) => { const s = xs.toSorted((a, b) => a - b); return s[Math.min(s.length - 1, Math.floor(p * s.length))]; };
   const fmt = (h) => (h < 48 ? `${h.toFixed(1)} h` : `${(h / 24).toFixed(1)} days`);
   const line = (label, xs) => console.log(`${label.padEnd(24)} median ${fmt(pct(xs, 0.5)).padEnd(9)} p90 ${fmt(pct(xs, 0.9))}`);
   
   console.log(`${repo}: ${rows.length} PRs merged into main since ${since}`);
   line('PR opened -> merged', rows.map((r) => r.review));
   line('First commit -> merged', rows.map((r) => r.toMerge));
   line('First commit -> released', rows.filter((r) => r.toProd !== null).map((r) => r.toProd));
   const patches = releases.filter((r) => !r.tagName.endsWith('.0'));
   console.log(`Releases: ${releases.length} in ${days} days (${patches.length} patch/hotfix), ${rows.filter((r) => r.toProd === null).length} PRs not released yet`);
   const slow = rows.toSorted((a, b) => b.review - a.review).slice(0, 3);
   console.log('Slowest reviews:', slow.map((r) => `#${r.number} ${fmt(r.review)}, ${r.size} lines`).join(' | '));

   Run it inside the repo:

   TerminalCopy

   node scripts/lead-times.mjs 30

   The script was not run against GitHub's live API for this lesson, so we checked it two ways. The GraphQL query validated against GitHub's published schema (a misspelt field such as mergedAtt is rejected with "Cannot query field"), and we ran the script unchanged against a stand-in gh that returned 22 PRs and 7 releases shaped exactly like GitHub's responses. Your numbers will differ; the output looks like this:

   OutputCopy

   your-org/partner-api: 22 PRs merged into main since 2026-09-07
   PR opened -> merged      median 9.0 h     p90 2.1 days
   First commit -> merged   median 21.0 h    p90 2.6 days
   First commit -> released median 3.6 days  p90 6.2 days
   Releases: 7 in 30 days (2 patch/hotfix), 0 PRs not released yet
   Slowest reviews: #148 4.1 days, 2000 lines | #159 2.9 days, 1500 lines | #143 2.1 days, 1125 lines

   Read it like a product manager. A PR waits a median of 9 hours for review, but the slowest three were 1,000 to 2,000 lines, which supports the size rule. Lead time to production is about three and a half days, mostly the wait for the weekly release; moving to two releases a week would cut it more than any coding speed-up. Two of seven releases were patches, a change fail rate of roughly 2 in 7, worth watching. Note the script's two simplifications: it treats every release as a deploy, and every non-.0 tag as a fix.

6. Measure recovery time from incident issues

   If every production incident gets an issue labelled incident, opened when it starts and closed when users are fine again, then recovery time is the time between the two. gh has jq built in, so one command gives the hours:

   TerminalCopy

   gh issue list --label incident --state closed --search "created:>=2026-09-07" \
     --json number,createdAt,closedAt \
     --jq 'map((.closedAt | fromdateiso8601) - (.createdAt | fromdateiso8601)) | map(. / 3600)
           | {incidents: length, hoursToRestore: map(. * 10 | round / 10)}'

   On two sample incidents (opened 08:10 and closed 13:05 UTC, opened 10:40 and closed 15:20 UTC), the same jq expression printed:

   OutputCopy

   {"incidents":2,"hoursToRestore":[4.9,4.7]}

7. Review the playbook with the team every quarter

   Book 45 minutes. Bring the four numbers for the last three months and the five slowest PRs. Ask three questions: which rule did we break most, and why? Which rule slowed us down without catching anything? What one change do we try next quarter? Record the decision as a PR to CONTRIBUTING.md, so the history of the playbook lives in Git like everything else.