From 07dc1ec5b3092195a9650e20e660714c1e2d86d4 Mon Sep 17 00:00:00 2001 From: Wijnand Modderman-Lenstra Date: Thu, 29 Oct 2026 17:44:29 +0100 Subject: [PATCH] Adapt agent guidance and supporting docs for BeatGlow --- .gitignore | 2 + AGENTS.md | 90 +++++++++++++++++++++++++++++- docs/agents/CodingConventions.md | 22 ++++++++ docs/agents/GoDocs.md | 21 +++++++ docs/agents/OperationalDoctrine.md | 20 +++++++ 5 files changed, 154 insertions(+), 1 deletion(-) create mode 100644 docs/agents/CodingConventions.md create mode 100644 docs/agents/GoDocs.md create mode 100644 docs/agents/OperationalDoctrine.md diff --git a/.gitignore b/.gitignore index 70e4893..c83fb6d 100644 --- a/.gitignore +++ b/.gitignore @@ -16,6 +16,8 @@ !README.md !LICENSE +!/AGENTS.md +!/docs/agents/*.md # README screenshots and wiring illustrations !/asset/image/beatglow-*.gif diff --git a/AGENTS.md b/AGENTS.md index 6f82b8c..5052896 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,13 @@ -# Git workflow +# BeatGlow agent guide + +BeatGlow is a Go music visualizer for embedded Linux audio players, especially +Raspberry Pi systems. Read the relevant code and these guides before changing it: + +- [Coding conventions](docs/agents/CodingConventions.md) +- [Operational guidance](docs/agents/OperationalDoctrine.md) +- [Go documentation](docs/agents/GoDocs.md) + +## Git and Gitea workflow - Create and switch to a feature branch before editing files or making commits. - Never commit directly on `main` or `master`. @@ -10,3 +19,82 @@ preserves those changes before committing them. - Open pull requests against the target branch; do not merge or push changes directly to `main` or `master` unless the user explicitly requests it. +- Base new work on `main` (normally `origin/main`); fetch when remote state matters. + Do not discard local changes or rewrite unrelated commits to update the base. +- Make focused commits with concise, descriptive subjects. +- Use the configured remote; this project uses Gitea. MR and PR refer to the same + review workflow here. Do not assume GitHub tooling works with Gitea. +- PR descriptions should explain the problem, resulting behavior, verification, + and remaining limitations. Reference an issue only when one exists, and mark it + closed only if the change completes it. Target the branch the work is based on. +- When API authentication is unavailable, push the requested feature branch and + provide the creation link; distinguish a pushed branch from a submitted PR. + +## Project map + +| Location | Responsibility | +| --- | --- | +| `cmd/beatglow/` | CLI, configuration discovery, installation and startup | +| `controller.go`, `context.go`, `hardware.go` | Component setup, events, rendering and audio processing | +| `config/` | HCL configuration and user settings; examples in `beatglow.conf` | +| `app/layout/`, `app/widget/`, `app/shader/`, `app/font/` | Screens, widgets, visual effects and embedded fonts | +| `player/` | Player contracts, registration and automatic detection | +| `player/mpd/` | MPD connections, commands, metadata and artwork | +| `player/raudio/`, `player/volumio/`, `player/moode/`, `player/runeaudio/` | Distribution-specific integrations; inspect implementation completeness | +| `player/all/` | Side-effect imports that load player drivers | +| `sound/` | PCM file/FIFO sources and audio diagnostics | +| `hardware/` | Display setup, combined displays, Linux network information and inputs | +| `internal/`, `testdata/` | Internal helpers and test fixtures | +| `asset/image/`, `doc/hardware/` | README illustrations and hardware references | + +Player detection runs in ascending priority order. Register distribution-specific +detectors ahead of generic MPD and import new drivers through `player/all/`. +Keep PCM sample format, channels and rate consistent with the configured producer. + +## Build and verification + +Use the Go version required by `go.mod` or newer. The display dependency currently +resolves to `../display`; check that checkout exists before diagnosing dependencies. +Do not silently remove the replacement or upgrade dependencies for unrelated work. + +```sh +# Existing Makefile target: Linux ARM binary, written to ./beatglow +make beatglow + +# Linux ARM64 binary without overwriting the repository's local executable +GOOS=linux GOARCH=arm64 go build -o /tmp/beatglow ./cmd/beatglow + +# Execute on Linux; narrow package paths for focused changes +go test ./... +go vet ./... + +# On macOS: compile Linux tests only; /usr/bin/true does not execute them +GOOS=linux GOARCH=arm64 go test -exec /usr/bin/true ./player/... + +git diff --check +``` + +Run `gofmt` on changed Go files. The Makefile has no test, lint, integration-test, +or generation targets. Linux wireless helpers prevent some packages from building +natively on macOS. Report cross-compilation separately from executed tests and +hardware verification. Use race tests on Linux when changing shared state. + +Known failures observed during setup include a log-format vet error in +`app/font/font.go` and a float32/float64 test mismatch in `internal/calc/calc_test.go`. +Recheck their current status; report unrelated failures without hiding them or +expanding scope automatically. + +## Assets and dependencies + +The repository uses an allowlist `.gitignore`. Verify new docs and assets appear +in Git; add narrow exceptions when needed. README images belong in `asset/image/`. +Check that all Markdown image targets exist and are tracked. + +PDF, BDF and TTF filters are configured in local `.gitattributes`; check the actual +attributes and Git LFS availability before adding or changing these files. Preserve +real assets and LFS objects. Never substitute placeholders to pass a build. + +## Sources + +Structure inspired by [Flow's AGENTS.md](https://github.com/onflow/flow-go/blob/master/AGENTS.md). +The linked local guides are project-specific adaptations, not verbatim imports. diff --git a/docs/agents/CodingConventions.md b/docs/agents/CodingConventions.md new file mode 100644 index 0000000..51beda9 --- /dev/null +++ b/docs/agents/CodingConventions.md @@ -0,0 +1,22 @@ +# Coding conventions + +- Use idiomatic Go, `gofmt`, and the surrounding package's naming and import style. + Extend existing contracts instead of introducing parallel registries or layers. +- Wrap propagated errors with useful context and `%w`. Use `errors.Is` or + `errors.As` when callers need to recognize them. +- Decide recovery at the caller: a disconnected MPD server can be retried, while + unusable startup configuration should return an error. Explain intentional + recovery; avoid silent failures and unnecessary process termination. +- Use structured Logrus fields for component, device, connection and path context. + Keep frame/sample loops quiet; log meaningful transitions and actionable failures. +- Keep display refreshes and controller event handling responsive. Close owned + connections, files and tickers; make goroutine shutdown explicit. Review channel + ownership and synchronization when changing lifecycle behavior. +- Validate protocol responses, HCL values, dimensions and PCM formats before use. + Respect Linux build constraints and hardware-specific dependencies. +- Put focused tests beside implementations. Cover parsing, malformed input, + detection precedence, failures and recovery with temporary files or fake servers. + Unit tests should run without physical GPIO, displays or a live MPD instance. + +Adapted from [Flow's coding guide](https://github.com/onflow/flow-go/blob/master/docs/agents/CodingConventions.md), +with BeatGlow-specific lifecycle, logging and hardware guidance. diff --git a/docs/agents/GoDocs.md b/docs/agents/GoDocs.md new file mode 100644 index 0000000..fbb4d4c --- /dev/null +++ b/docs/agents/GoDocs.md @@ -0,0 +1,21 @@ +# Go documentation + +- Document new or changed exported APIs and interfaces. Explain private code when + its lifecycle, protocol behavior or invariants are not clear from the code. +- Start API comments with the declared name and write complete sentences. Use + paragraphs and Go doc links such as `[Player]` for relevant Go identifiers. +- Describe the contract: parameter constraints, units, defaults, return values, + blocking behavior and resource ownership when they matter to callers. +- For error returns, explain actionable failure conditions and recognizable + sentinel errors that the implementation actually returns. Do not invent error + types, guarantees or recovery behavior. +- State concurrency restrictions explicitly. Do not assume a type is safe for + concurrent use simply because no warning exists. +- Keep interface contracts and implementations consistent. Explain meaningful + deviations rather than copying comments mechanically. +- For documentation-only tasks, preserve runtime behavior. Correct inaccurate + documentation after checking the implementation; keep separate logic fixes scoped. +- Wrap prose around 100 characters where practical. Avoid documenting obvious + implementation steps or adding repetitive boilerplate. + +Adapted from [Flow's Go documentation guide](https://github.com/onflow/flow-go/blob/master/docs/agents/GoDocs.md). diff --git a/docs/agents/OperationalDoctrine.md b/docs/agents/OperationalDoctrine.md new file mode 100644 index 0000000..e483784 --- /dev/null +++ b/docs/agents/OperationalDoctrine.md @@ -0,0 +1,20 @@ +# Operational guidance + +- Follow the user's task and established preferences. Continue authorized work + without repeatedly asking for confirmation; clarify genuinely missing decisions. +- Inspect the code, branch, diff and relevant documentation before making changes. + Verify external protocol behavior against upstream documentation when needed. +- Keep changes within scope and preserve unrelated work. Explain a necessary + scope change instead of silently bundling cleanup or dependency updates. +- Communicate directly and briefly. Explain findings, behavior changes and remaining + uncertainty; avoid flattery and unsupported claims. +- Review the surrounding component after editing, including configuration, + registration, lifecycle and callers affected by an interface change. +- Test the behavior that changed. State which tests ran, which checks only + compiled, and what requires Linux, hardware, network access or authentication. +- Describe recoverable device/server failures realistically. Do not label an issue + critical without evidence or claim a fix is verified on hardware without testing it. +- Finish with concise results, links to changed files or the PR, and material + limitations. Never report a PR created when only its branch was pushed. + +Adapted from [Flow's operational guide](https://github.com/onflow/flow-go/blob/master/docs/agents/OperationalDoctrine.md).