3.5 KiB
Repository Guidelines
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. Preserve Xorg correctness while allowing capability-based Wayland degradation. Keep Tentacles external and responsive.
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. No numeric coverage target is configured. Report automated, installed-binary, physical-input, audible-speech, and Braille-display checks separately.
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.