44 lines
3.5 KiB
Markdown
44 lines
3.5 KiB
Markdown
# 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/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. 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`.
|