# Contributing

This guide covers the branch, commit, and pull-request workflow for SupplierPulse /
Kadi-v2. It complements [`CLAUDE.md`](CLAUDE.md) (AI-agent operating context) and
[`AGENTS.md`](AGENTS.md) (human review guidelines).

## Prerequisites

- Node.js ≥ 20.9 (next 16 floor); the validated dev / CI baseline is **24.x**
  (`.nvmrc` pins `24`).
- npm ≥ 10. Install with `npm install`; CI uses `npm ci` against `package-lock.json`.

## Branches

- `main` is the production branch (auto-deployed to Vercel). Keep it green.
- Create short-lived feature branches off an up-to-date `main`:
  `feat/...`, `fix/...`, `refactor/...`, `chore/...`, `docs/...`.
- Before branching, confirm local `main` has no operator side-commits:
  `git log --oneline origin/main..main` should be empty.

## Commits

- Use [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`,
  `refactor:`, `chore:`, `docs:`, `test:`.
- Keep commits focused; do not bundle unrelated changes under one message.
- Author email must be a real, resolvable address (Vercel rejects `*.local`).

## Before you push — local gates

Run the same checks CI enforces:

```bash
npm run typecheck
npm run lint
npm run test
CHECK_FORBIDDEN_LEVEL=error npm run check:portability
npm run build
```

`check:portability` bundles: `check:profiles`, `check:forbidden`,
`check:boundaries`, `check:openapi`, `check:csp`, `check:secrets`,
`check:hardcoded-colors`, `check:bmw-fonts`. The `CHECK_FORBIDDEN_LEVEL=error`
prefix makes the forbidden-strings check fail on the first hit (the CI-equivalent
strict mode); without it the check is warn-only.

## Pull requests

- Open the PR against `main` using the repository PR template.
- A PR is "done" only when typecheck, tests, and the portability gate are green and
  the change is documented (see Documentation rules below).
- Add `Closes KAR-<n>` in the PR body for each Linear issue the PR resolves.

### CI workflows

PRs run, among others:

- `portability-matrix` — typecheck, tests, and the portability checks (hard gates;
  lint currently soft-gated during the React 19 cleanup).
- `security-gitleaks`, `security-semgrep` — secret + SAST scans (hard gates).
- `security-deps` — `npm audit` (informational).
- `security-codeql` — CodeQL (enabled when GitHub Advanced Security is available).
- `lighthouse-ci` — performance budget on the Vercel preview.

See `docs/foundation/` for the CI / security reference and the list of required
status checks for branch protection.

## Documentation

- Add a `CHANGELOG.md` entry for every completed task (newest on top,
  `## YYYY-MM-DD – Feature-Name`).
- Update `TODO.md` (strike or remove done items; add new open items).
- Architectural decisions go in `docs/adr/` (ADR-020: no customer-specific
  exception without an ADR).
- Database changes: add the SQL file and register it in [`MIGRATIONS.md`](MIGRATIONS.md)
  (class, depends-on, RLS effect, apply order). Never apply SQL to production without
  operator approval.

## Code style

See the "Code Style", "Naming Conventions", and "Safe Working Rules & Stop
Conditions" sections in [`CLAUDE.md`](CLAUDE.md).