# Repository Guidelines ## CRITICAL: Init-System Independence Cthulhu must never depend on a specific Linux init system or service manager. This applies to the reader, Tentacles, process supervision, installation, packaging, and required tests. Do not require systemd, `systemd-run`, `systemctl`, or a systemd user manager. Use init-independent Linux interfaces and detect the capabilities actually available. Cthulhu and its Tentacles must work on non-systemd distributions, including Artix. ## Before Starting a Fix or Feature Inspect `git status --short --branch`, confirm the intended branch and upstream, and complete `git pull --ff-only` before starting implementation. If local and upstream commits have diverged, resolve that divergence with a normal merge before proceeding; never discard local work to make the pull succeed. If a merge or rebase is already in progress, finish it first. Preserve uncommitted changes and diagnostic files; do not automatically stash, reset, or clean them. On every branch other than `testing` or `master`, also fetch the maintained repository's latest `testing` branch and merge it into the working branch. With the maintained repository configured as `origin`, use `git fetch origin` followed by `git merge origin/testing`. Resolve conflicts, run the relevant checks, and finish any merge commit before starting the new work. An unresolved or failed synchronization blocks implementation. Do not merge `testing` into `master` as part of this preparation; release integration is separate. After synchronization, check whether the reported issue still exists and inspect recent changes before implementing a fix. Another contributor may already have fixed it. See [the contributor synchronization procedure](CONTRIBUTING.md#update-your-branch-before-starting-work), including instructions for a new branch without an upstream. ## Project Structure & Module Organization Cthulhu is a Go Linux screen reader. `cmd/` contains executables; `internal/` owns reader subsystems. Embedded audio lives in `assets/sounds/`, Tentacle libraries in `sdk/`, native harnesses in `tests/`, and parity records in `testdata/`. Go tests sit beside implementation files. Arch packaging lives in `distro-packages/Arch-Linux/cthulhu-git/`. ## Build, Test, and Development Commands Use Go 1.24+ with CGO and development libraries listed by the Arch `PKGBUILD`. - `go build -o build/cthulhu ./cmd/cthulhu`: build the reader. - `go build -tags brlapi -o build/cthulhu-braille ./cmd/cthulhu-braille`: build the Braille helper. - `go test ./... -count=1`: run default tests; native cases may skip. - `go test -tags brlapi ./... -count=1`: run packaging checks. - `go vet ./...`: check common Go errors. - `go run ./cmd/parityledger validate testdata/parity-ledger.csv`: validate parity records. - `./build/cthulhu --check-config`: validate settings; `./build/cthulhu` starts the reader. ## Coding Style & Naming Conventions Use `gofmt`, exported PascalCase identifiers, private camelCase identifiers, and lowercase packages. Preserve license headers. Follow existing Python conventions; run `shellcheck` for edited shell scripts. Keep complete user-facing messages separate from internal identifiers and preserve deliberate speech/Braille segmentation. ## Behavior & Accessibility Safeguards Read [CONTRIBUTING.md](CONTRIBUTING.md) for detailed safeguards. Compare accepted behavior with Python on `legacy`; use current Orca as the primary reference for Mozilla and LibreOffice support. Follow [LIBREOFFICE_SUPPORT.md](LIBREOFFICE_SUPPORT.md) for Office integration boundaries. Preserve unrelated work and active diagnostic logs; obtain authorization before replacing a running reader. Fix regressions in the shared subsystem when appropriate. Identify state ownership, lifetime, reset, and cancellation; keep native callbacks and input/focus handling bounded. Keep Tentacles external and responsive. X11/Xorg is the primary supported display environment. Wayland support is secondary and must not regress Xorg behavior. Xorg regressions are critical blockers for merging and release. If a Wayland change cannot preserve Xorg correctness, defer that change. Use capability checks and graceful degradation for Wayland support. Prefer core Go implementations for features users expect from the reader itself; use Tentacles for extensions. Expose GUI controls through accessibility APIs. Keep outer preferences combo widgets `can-focus=False`; verify Tab/Shift+Tab, popup selection, and Apply/reload. Validate versioned TOML settings through persistence and runtime consumption. Protect passwords; redact private debug output before sharing. ## Testing Guidelines Use Go's `testing` package, `*_test.go`, and `TestBehavior` functions. Start with the affected package. Use deterministic synchronization and generic fixtures. Native checks need their relevant harness, such as `python3 tests/native_atspi.py`. Specify a 24-bit Xvfb screen for Qt fixtures: Slint's `xvfb-run` defaults to 8-bit, which can crash Qt text-cursor painting. No numeric coverage target is configured. Report automated, installed-binary, physical-input, audible-speech, and Braille-display checks separately. For performance work, run the relevant `BenchmarkBehavior` functions before and after changes using repeated runs and allocation reporting. Add or expand representative benchmarks when investigating a new bottleneck; keep fixture construction outside timed loops and check that the intended work actually happens. Preserve announcement content, ordering, interruption, focus, and Braille behavior. Benchmark timing alone does not establish a bug or live responsiveness, and noisy timing changes must not become automatic pass/fail thresholds. See [benchmark procedures](docs/testing/benchmarks.md) for commands and measurement limits. Plain `go test` does not run benchmarks. ## Commit & Pull Request Guidelines Use short descriptive subjects consistent with history. Confirm the intended target branch; `legacy` preserves Python. Describe behavior, issues, regressions checked, skipped checks, and remaining live acceptance. Human diff review and testing precede submission under the policy in `CONTRIBUTING.md`. ## Guide Maintenance Update this guide when working rules, repository layout, commands, or verification requirements change. Replace stale guidance instead of appending progress reports; keep detailed procedures in `CONTRIBUTING.md`.