ekklesiaandClaude Opus 5.5
d5b1fdf119
What the repository is and where things are, the release rules agents must never bend (a version is used once, nothing is rebuilt, a person runs every release step), branches, the checks that exist and what each proves, and the working conventions, including filing an issue for what is found outside the task at hand. Co-Authored-By: Claude Opus 5.5 <[email protected]>
5.0 KiB
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 indocs/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:
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 ismaster. Branch from an up-to-dateorigin/master(ororigin/release/X.Yfor a maintenance fix), one branch per pull request. Never push tomasterorrelease/*, never merge your own pull request. - Every defect fix gets a test in
tests/;check.shpicks 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.