Skip to content

Developer Conventions ​

Day-to-day conventions for working in the PPP monorepo. This is the "how we actually ship things here" page — the rules that don't show up in lint errors but do show up in PR reviews.

For non-negotiable technical rules (type safety, no-console.log, migration discipline), see Code Standards.

Git Workflow ​

Branches ​

  • uat is the integration branch. All feature work merges into uat first and is deployed to the UAT environment.
  • main tracks what's in production. It only receives commits via controlled uat → main release PRs (typically with -s ours merges to bridge divergence).
  • Feature/fix/chore branches are created from origin/uat, named by type and issue number, e.g. feature/issue-1234, fix/issue-4895-cv-upload, chore/issue-5143-delete-deploy-marketing.

Git worktrees — the main workspace stays on uat ​

PPP uses git worktrees for all feature work. The main workspace (C:\Git\ppp / /workspaces/ppp) stays on uat at all times — never switch branches there unless the user explicitly requests it.

bash
# Create a worktree for a new issue
git worktree add .worktrees/issue-<N> -b feature/issue-<N> origin/uat

# Work in the worktree
cd .worktrees/issue-<N>
# … make changes, commit, push …

# Return to the main workspace
cd /workspaces/ppp

# Clean up after the PR merges
git worktree remove .worktrees/issue-<N>

Worktrees let multiple parallel feature branches coexist without blowing away node_modules or forcing a stash-juggling ritual when you jump between issues.

Pre-commit hooks ​

Husky runs lint-staged on every commit. Lint-staged runs Prettier against staged files and fails the commit if formatting is off. The hook also runs any type/lint checks scoped to the changed paths.

If a hook fails, fix the underlying issue — do not bypass with --no-verify unless the user has explicitly asked for it. When a hook fails, the commit did not happen, so never use git commit --amend to retry; create a fresh commit instead.

Conventional commits ​

PPP uses Conventional Commits with Commitizen. The prefix determines the release-note section and must match the type of change:

PrefixUse for
feat(scope): ...New feature or user-visible enhancement
fix(scope): ...Bug fix
chore(scope): ...Tooling, deps, refactors that aren't user-visible
refactor(scope): ...Internal restructuring with no behaviour change
docs(scope): ...Documentation-only change
test(scope): ...Test-only change
ops(scope): ...Operational/runtime config
deploy(scope): ...Deployment pipeline or release mechanics

Run pnpm commit from the repo root to get an interactive Commitizen prompt that builds a valid message.

Pull Requests ​

Title convention ​

The PR title is the squash-merge commit message, so it must follow the Conventional Commits format and include a - fixes #<N> suffix where possible so the issue auto-closes when the PR merges.

fix(signup): auto-mount PaymentIntent and default billing country to registration country - fixes #5151
feat(pricing): bump CPD Home to $299 AUD / £159 GBP — fixes #5111
chore(mobile): delete redundant deploy-marketing.yml — fixes #5143

Closing keywords ​

GitHub auto-closes issues when the merged PR's title OR body contains one of the closing keywords: fixes #N, closes #N, resolves #N. The keywords are strict — Fix #N (capital, missing plural) and fixes: #N (with colon) both fail to auto-close.

Body structure ​

A typical PR body looks like:

markdown
## Summary

- 1-3 bullets describing what changed and why

## Test Plan

- [ ] Manual verification steps
- [ ] Any CI gates that need attention

fixes #<N>

Issue Labelling ​

Every open issue must carry exactly one of bug or enhancement as a top-level tag. This makes the weekly triage ritual fast — a reviewer can filter the board by bug and triage everything critical in one pass.

LabelUse for
bugSomething is broken, regressing, or behaving against spec
enhancementEverything else: new features, tech debt, refactors, ops tasks, research spikes, deploy tasks
questionExempt from the bug/enhancement rule — questions aren't trackable work

When you create an issue via gh issue create or a workflow, always pass bug or enhancement in the labels array. The issue-auto-label workflow is a safety net that defaults new issues to enhancement, but don't rely on it — tag at creation.

Secondary labels to consider:

  • for-discussion — items that need Matt's specific review or feedback before closing (e.g. UX decisions, clinical workflow, pricing/billing)
  • on-hold — parked items with open questions; typically need a product decision before implementation can proceed
  • epic — umbrella issues that track multiple children
  • Module labels like mobile, docs, devops, marketing — help scoping

BDD-First Rule ​

Every issue that touches instances/ppp/ or api/backend-ppp/ must include a corresponding BDD scenario change. If a PR has no .feature file change and touches those paths, the PR description must include an explicit justification.

The order is always: scenario first, implementation second. The scenario is the acceptance criteria. If you can't write a scenario, the issue isn't well-defined enough to implement.

Issue typeRequired tagLocation
Bug fix@regressionMatching .feature file — a scenario that would have caught the bug
New feature@smokeMatching .feature file — 1-2 critical path scenarios
New journey@smoke + @regression@smoke for the happy path, @regression for the failure path

Tag every new scenario with @issue-<N> so the trace from scenario → issue → PR is automatic.

Step definitions grow organically — if your scenario needs a step that doesn't exist, add it to the matching steps/*.steps.ts file. Reuse existing steps wherever possible; the step library compounds with each closed issue.

Feature Specifications ​

Before modifying any named feature, read its spec file in docs/features/. If your change causes the implementation to diverge from the acceptance criteria, you must update the spec with the reason in the Change Log at the bottom of the spec file. Never silently remove functionality that appears in a spec.

See docs/features/README.md for the full index. Related BDD scenarios live in instances/ppp/e2e/bdd/features/ and are executable via playwright-bdd.

Plan Before Building ​

  • Enter plan mode for any task with 3+ steps or architectural decisions.
  • If an approach fails or goes sideways, stop and re-plan rather than pushing through.
  • Every plan should include verification steps, not just build steps.
  • Write specs upfront to reduce ambiguity — "we'll figure it out as we go" is a sign of scope creep.

Verify Before Done ​

Never mark work as done without running the CI-equivalent gates locally. The table below maps changed areas to the commands you need to run; CI enforces exactly the same commands as Tier 1 gates.

Changed areaCommands
api/backend-ppp/pnpm tsc && pnpm lint && pnpm lint:no-console
instances/ppp/npx tsc --noEmit -p tsconfig-lint.json && pnpm lint && pnpm lint:no-console
packages-shared/ppp/pnpm tsc (from root)
Any of the abovenode .github/scripts/check-no-any.mjs
Backend test filesnpx tsc --noEmit -p tsconfig.test.json

Diff your changes against the base branch before requesting review. Ask yourself: "Would a senior engineer approve this PR?"

Autonomous Problem Solving ​

  • When given a bug report or failing CI, investigate and fix it. Don't ask for hand-holding.
  • Point at logs, errors, and failing tests, then resolve them.
  • Zero context-switching required from the requester.
  • Fix failing CI tests without being told how.

Development Environment ​

Prerequisites ​

  • Node.js ≥ 22.14.0
  • pnpm ≥ 9
  • Docker (for backend integration tests against a local Postgres)

Initial setup ​

bash
pnpm install          # install all dependencies
pnpm build            # build all packages — required before running apps
pnpm build:force      # force rebuild, ignoring turbo cache

Running the stack ​

bash
# Frontend (from instances/ppp/)
pnpm start            # http://localhost:3000

# Backend (from api/backend-ppp/)
pnpm start            # http://localhost:4000

# Storybook
pnpm storybook        # http://localhost:6006

Common commands ​

bash
pnpm format-lint      # check formatting
pnpm format-fix       # auto-fix formatting
pnpm lint             # lint all workspaces
pnpm tsc              # type-check all workspaces
pnpm test             # run all tests
pnpm clean            # remove node_modules and build artifacts

Style Highlights ​

  • Comments in PPP code start with 🤗 for visual consistency.
  • Variable names should be clear and descriptive — prefer monthlyActivityCount over cnt.
  • Single-line if statements don't need brackets when the body is a single statement.
  • Prefer early returns over deep nesting.
  • Extract functions when a block grows beyond ~40 lines; name them after what they do, not how they do it.

Where to Go Next ​

Internal documentation — org members only