nilesh.pandClaude Opus 4.8
035711f08c
- CLAUDE.md + AGENTS.md: canonical guiding principles for AI agents and developers (tenant isolation, no RLS, stack, security, conventions, environment gotchas) - SECURITY.md: required security controls (isolation, secrets, auth, input handling, least privilege) with VAPT status - GOVERNANCE.md: how changes are validated before merge — deterministic gates + AI review, risk tiers, human accountability - CONTRIBUTING.md: code hygiene, definition of done, file hygiene - docs/wiki/: product reference (overview, domain model, features, roles & access, API reference, glossary) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
74 lines
3.0 KiB
Markdown
74 lines
3.0 KiB
Markdown
# Contributing & code hygiene
|
|
|
|
Working rules for anyone (human or AI) changing this repository. Read
|
|
[CLAUDE.md](CLAUDE.md) for the architecture and the full conventions; this is
|
|
the day-to-day hygiene.
|
|
|
|
## First-time setup
|
|
|
|
```powershell
|
|
npm run setup # frontend + e2e dependencies, Playwright browser
|
|
npm run db:migrate # create and seed the app database
|
|
npm run db:test # create the empty database the Go tests use
|
|
.\scripts\install-hooks.ps1 # activate pre-commit / pre-push gates
|
|
```
|
|
|
|
`core.hooksPath` is a local git setting — every clone must run the last step.
|
|
|
|
## Branching & commits
|
|
|
|
- **Branch from `main`.** Never commit or push directly to `main`; it is
|
|
protected and changes land via pull request.
|
|
- One logical change per commit; write a clear subject line (imperative mood)
|
|
and a body explaining the *why*.
|
|
- Keep attribution lines as the project specifies for commits and PRs.
|
|
- If a push is rejected because the remote moved, **rebase** onto it (keep
|
|
history linear) — do not force-push.
|
|
|
|
## Code style
|
|
|
|
- **Go:** `gofmt` and `go vet` must be clean. Wrap errors with `%w` and context.
|
|
SQL only in `repository/`, always parameterised.
|
|
- **Angular/TypeScript:** `tsc` clean; Prettier formatting; standalone
|
|
components and signals; services in `core/`. No `any` where a type is known.
|
|
- **SCSS:** theme-aware and responsive; no horizontal scroll at 390px.
|
|
- **SQL/migrations:** idempotent and re-runnable; tenant tables carry
|
|
`tenant_id` with `ON DELETE CASCADE`.
|
|
|
|
## Tests are part of the change
|
|
|
|
- Every behavioural change ships with tests. New behaviour gets a **scenario
|
|
card** in `qa/scenarios/` first (see [`qa/README.md`](qa/README.md)).
|
|
- Run the relevant layer before pushing: `.\run-tests.ps1 -Layer <layer>`.
|
|
The pre-push hook runs the unit layers automatically.
|
|
- **Never weaken an assertion** to get green. Assert on observable behaviour,
|
|
not implementation.
|
|
- Leave data as you found it — a test that creates a booking cancels it.
|
|
|
|
## Definition of done
|
|
|
|
A change is done only when **all** hold:
|
|
|
|
- [ ] Tests for the change pass (`run-tests.ps1` green).
|
|
- [ ] For UI/binding work, the evidence report proves the scenario.
|
|
- [ ] No secret added; `.env` untouched in the diff.
|
|
- [ ] Scope is exactly the task — nothing unrelated.
|
|
- [ ] Docs updated if behaviour, API, or conventions changed (incl. this file,
|
|
CLAUDE.md, the wiki).
|
|
- [ ] `gofmt`/`go vet`/`tsc` clean.
|
|
|
|
## File hygiene
|
|
|
|
- **Never commit:** `.env`/secrets, `node_modules/`, build output
|
|
(`dist`, `bin`, `.angular`), run artifacts (`.testlogs/`, `e2e/results/`,
|
|
`e2e/evidence-report/`, `.run/`), coverage files, PDFs. These are git-ignored;
|
|
keep it that way.
|
|
- Do not check in large binaries or generated reports — they are regenerated.
|
|
- Keep the docs in sync with the code; a stale wiki is worse than none.
|
|
|
|
## Destructive actions
|
|
|
|
Ask before anything hard to reverse or outward-facing (dropping data, force
|
|
operations, pushing to a shared remote, deleting). `db:reset` drops the dev
|
|
database — expected in dev, never run it against shared data.
|