Merge pull request 'docs: a CLAUDE.md for agents working in this repository' (#7) from docs/claude-md into master
Reviewed-on: #7
This commit was merged in pull request #7.
This commit is contained in:
@@ -0,0 +1,86 @@
|
||||
# CLAUDE.md
|
||||
|
||||
Guidance for Claude Code (and other coding agents) working in this repository. It points at the
|
||||
authoritative sources rather than restating them, because restated details drift. Inspect the actual
|
||||
source, tests, scripts, and workflows before relying on anything here or on memory of a prior
|
||||
session.
|
||||
|
||||
## What this repository is
|
||||
|
||||
**Ekklesia Classroom**: the `ekklesia-classroom` Debian package (amd64, Debian 13 "trixie") that turns
|
||||
a laptop or desktop into a locked-down KDE Plasma (Wayland) classroom machine for a church: a
|
||||
teacher's launcher, the classroom browser and Wonder Ink, Presentations, DVD playback, printing,
|
||||
Parent Call messaging, networking and Wi-Fi adoption, a display-size setting, and an updater that
|
||||
installs new releases unattended. Machines receive it over the air from the update server
|
||||
(`https://updates.riverofglorymn.org`), on the **stable** or **canary** ("Preview") channel.
|
||||
|
||||
It is a separate product from the Ekklesia platform repository (`Zayin/Ekklesia`) and its modules,
|
||||
and shares no code with them. The platform roadmap (`../ROADMAP.md`, section *Classroom*) plans
|
||||
Classroom as a future first-party module whose scope is deliberately **not locked yet**. Do not build
|
||||
platform integration (modules, platform devices, accounts) here speculatively; that starts from a
|
||||
scope decision, not from code.
|
||||
|
||||
Where things are:
|
||||
|
||||
| Path | What |
|
||||
| --- | --- |
|
||||
| `scripts/` | Everything installed as a command: the session, launcher, browser, updater, admin tools |
|
||||
| `lib/` | The Python modules those commands share (`classroom_config.py`, printing, presentations, …) |
|
||||
| `config/`, `systemd/` | Plasma, SDDM, polkit, D-Bus, udev, and systemd units the package installs |
|
||||
| `packaging/debian/` | `control.template` and `postinst` |
|
||||
| `tests/test-*.sh` | Every automated test; each runs with no screen and no container |
|
||||
| `tools/` | `check.sh`, `build-release.sh`, `release-gate.sh`, the release tooling, and `lab/` |
|
||||
| `docs/` | How each feature works and why. `releasing.md` and `testing.md` are the process |
|
||||
|
||||
## Releases are never rebuilt, and a person makes every decision
|
||||
|
||||
Read `docs/releasing.md` before touching anything release-shaped. Its rules are not negotiable:
|
||||
|
||||
- **A version is used once.** Once a file of that name has been on the update server, it is never
|
||||
rebuilt or replaced. Tags (`v` + version) are never moved.
|
||||
- **The file the gate passed is the file every room installs**, byte for byte. Nothing is rebuilt
|
||||
after Release 1.
|
||||
- **A person runs every release step**: the Release workflows, `update_canary.sh`,
|
||||
`update_stable.sh`, and the physical checks in `docs/testing.md`. Never run them, publish to the
|
||||
update server, reach a classroom machine or the church server (`10.40.0.2`), or create or push a
|
||||
tag. Tests use stand-in servers; keep it that way.
|
||||
|
||||
## Branches
|
||||
|
||||
`master` is the next feature release; `release/X.Y` is a maintenance line (fixes only). A fix made on
|
||||
`release/X.Y` is merged **forward** into `master`, never cherry-picked backwards. `experiment/*` is
|
||||
never built as a release. See `docs/releasing.md` → *Branches*.
|
||||
|
||||
## Verification
|
||||
|
||||
`tools/check.sh` is the one list of checks, run by CI and by every release build:
|
||||
|
||||
```bash
|
||||
tools/check.sh # sources, the manual, every tests/test-*.sh
|
||||
tools/check.sh --base <ref> # and the change since <ref> is clean (git diff --check, no build output)
|
||||
```
|
||||
|
||||
Beyond that: `tools/build-release.sh VERSION` builds the package (after `check.sh`);
|
||||
`tools/release-gate.sh` installs it on a clean Debian container, fresh and as an upgrade (needs
|
||||
Docker); `tools/lab/` exercises the real Plasma session and needs the nested session on the
|
||||
development VM; and real hardware is `docs/testing.md`. Unit checks passing is not evidence that a
|
||||
desktop behaviour works; say which of these you ran.
|
||||
|
||||
CI is `.gitea/workflows/ci.yml` (checks, then package and container gate) on the `ekklesia-ci`
|
||||
runner. Read its open issues before trusting a red or green run.
|
||||
|
||||
## Working conventions
|
||||
|
||||
- Canonical remote: `ssh://[email protected]:2222/Zayin/Classroom_Desktop.git` (web and API:
|
||||
`https://git.zayin.net`). The default branch is `master`. Branch from an up-to-date `origin/master`
|
||||
(or `origin/release/X.Y` for a maintenance fix), one branch per pull request. Never push to
|
||||
`master` or `release/*`, never merge your own pull request.
|
||||
- Every defect fix gets a test in `tests/`; `check.sh` picks it up with nothing else to edit.
|
||||
- Plain language in anything a teacher sees.
|
||||
- Report what you find. A defect, flaky test, documentation conflict, or CI problem outside the task
|
||||
at hand gets an issue in the repository it belongs to, as soon as you find it. Search for an
|
||||
existing issue first; something fixed in the same pull request goes in its description instead. Be
|
||||
descriptive: what you saw, the evidence (run and job links, commit, file and line), how to
|
||||
reproduce it, the impact, and options, and never a secret. Label it `found-by-claude` (an agent
|
||||
that cannot apply labels ends the body with a line saying so), leave it unassigned, and list what
|
||||
you filed when you report back.
|
||||
Reference in New Issue
Block a user