6.3 KiB
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, 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/cthulhustarts 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 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 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 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.