home-pump/CONTRIBUTING.md

Repository rules

What we build: docs/spec.md. Plan: docs/roadmap.md. Reasons: 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.