rootandClaude Opus 5.5
b2b946d4bc
CI / Check (gateway, backend, frontend) (push) Successful in 2m2s
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
63 lines
2.9 KiB
Markdown
63 lines
2.9 KiB
Markdown
# Repository rules
|
|
|
|
What we build: [docs/spec.md](docs/spec.md). Plan: [docs/roadmap.md](docs/roadmap.md).
|
|
Reasons: [docs/decisions/](docs/decisions/).
|
|
|
|
## Branches and pull requests
|
|
|
|
- `master` is always deployable and matches what runs on the Pi.
|
|
- Every change goes through a pull request on Gitea; no direct commits to `master`.
|
|
- Branch names: `feat/…`, `fix/…`, `docs/…`, `chore/…`, `refactor/…`.
|
|
- One topic per PR, small enough to review in one sitting. Merge only with green CI.
|
|
- `archive/spring-boot-attempt` is reference only. Never merge it.
|
|
|
|
## Commits
|
|
|
|
- English, Conventional Commits: `fix(health): restart without /health polling`.
|
|
- Imperative subject ≤ 72 characters; the body says why when it is not obvious.
|
|
- Each commit builds and passes tests.
|
|
|
|
## Code
|
|
|
|
- Three parts, each with its `Dockerfile` and `compose.yaml` (ADR-010): `gateway/` and `backend/`
|
|
in Java 21 with Maven and no framework (ADR-001), `frontend/` in React and TypeScript (ADR-008).
|
|
- `scripts/check.sh` is the gate: doc limits, secret scan, build and tests. CI runs it, and so
|
|
does the pre-push hook once enabled with `git config core.hooksPath .githooks`.
|
|
- Readable first: small classes and methods, names from the domain, comments only for the why.
|
|
- No dead code, no unused config, no duplicated logic, no speculative abstractions.
|
|
- Every behaviour change has a test. Modbus is tested against `MockModbusServer` only.
|
|
|
|
## Safety
|
|
|
|
- Tests and local runs never use the real controller or the `Dom_Pompa` database.
|
|
- A register is written only if it is on the allowlist (min, max, step) and verified in
|
|
`docs/frisko/`.
|
|
- Changes to how or when we write to the controller need a test of the failure case.
|
|
|
|
## Knowledge and docs
|
|
|
|
Docs are written so an agent needs little context: read only what the task touches.
|
|
|
|
| File | Limit | Changes |
|
|
|---|---|---|
|
|
| `CLAUDE.md` | 40 lines | rarely |
|
|
| `docs/spec.md` | 120 lines | when scope or architecture changes |
|
|
| `docs/roadmap.md` | 80 lines | every milestone |
|
|
| `docs/decisions/NNN-*.md` | 40 lines | never after acceptance; supersede with a new ADR |
|
|
| `docs/frisko/<topic>.md` | 120 lines | when knowledge is verified |
|
|
| `<package>/CLAUDE.md` | 30 lines | rules of that layer |
|
|
| `research/<source>/` | none | raw vendor material, kept as found; read only on demand |
|
|
|
|
- Limits are checked by `scripts/check.sh`.
|
|
- No status, audit or log documents: the state is git history and the roadmap.
|
|
- Closing a milestone compresses it to one line in the roadmap and removes its working notes.
|
|
- English everywhere; the UI is Polish.
|
|
|
|
## Configuration, secrets, releases
|
|
|
|
- No secrets in git. Production config lives on the Pi and next to the Kraków stacks, outside
|
|
the images.
|
|
- Release only from `master` with `scripts/release.sh vMAJOR.MINOR.PATCH`: it tags master and
|
|
CI publishes the three images. On the Pi `./update.sh <version>` goes back if it is unhealthy.
|
|
- After an update, watch the journal and Grafana for at least one polling cycle.
|