From 7916bc0b78856e5bb89187f37d7750c268a361be Mon Sep 17 00:00:00 2001 From: Wijnand Modderman-Lenstra Date: Thu, 29 Oct 2026 17:41:48 +0100 Subject: [PATCH 1/3] Require feature branches in agent instructions --- AGENTS.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..6f82b8c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,12 @@ +# Git workflow + +- Create and switch to a feature branch before editing files or making commits. +- Never commit directly on `main` or `master`. +- Use descriptive branch names, such as `feat/mpd-fifo-output-monitoring`, + `fix/readme-images`, or `chore/agent-instructions`. +- Continue on an existing feature branch when working on the same task. Create a + separate branch from the target branch for unrelated work. +- If changes already exist on `main` or `master`, create a feature branch that + 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. -- 2.54.0 From 07dc1ec5b3092195a9650e20e660714c1e2d86d4 Mon Sep 17 00:00:00 2001 From: Wijnand Modderman-Lenstra Date: Thu, 29 Oct 2026 17:44:29 +0100 Subject: [PATCH 2/3] 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). -- 2.54.0 From d489a9b85c7f8c28e7b15f38ada7c307187a1c08 Mon Sep 17 00:00:00 2001 From: Wijnand Modderman-Lenstra Date: Thu, 29 Oct 2026 18:40:07 +0100 Subject: [PATCH 3/3] Refine agent branch naming and Go formatting guidance --- AGENTS.md | 4 ++-- docs/agents/CodingConventions.md | 5 +---- docs/agents/GoDocs.md | 2 -- docs/agents/OperationalDoctrine.md | 2 -- 4 files changed, 3 insertions(+), 10 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 5052896..23d6bcd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,7 +11,7 @@ Raspberry Pi systems. Read the relevant code and these guides before changing it - Create and switch to a feature branch before editing files or making commits. - Never commit directly on `main` or `master`. -- Use descriptive branch names, such as `feat/mpd-fifo-output-monitoring`, +- Use descriptive branch names, such as `feature/mpd-fifo-output-monitoring`, `fix/readme-images`, or `chore/agent-instructions`. - Continue on an existing feature branch when working on the same task. Create a separate branch from the target branch for unrelated work. @@ -74,7 +74,7 @@ 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, +Run `goimports` 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. diff --git a/docs/agents/CodingConventions.md b/docs/agents/CodingConventions.md index 51beda9..e4844ad 100644 --- a/docs/agents/CodingConventions.md +++ b/docs/agents/CodingConventions.md @@ -1,6 +1,6 @@ # Coding conventions -- Use idiomatic Go, `gofmt`, and the surrounding package's naming and import style. +- Use idiomatic Go, `goimports`, 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. @@ -17,6 +17,3 @@ - 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 index fbb4d4c..ea2bb52 100644 --- a/docs/agents/GoDocs.md +++ b/docs/agents/GoDocs.md @@ -17,5 +17,3 @@ 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 index e483784..73483ed 100644 --- a/docs/agents/OperationalDoctrine.md +++ b/docs/agents/OperationalDoctrine.md @@ -16,5 +16,3 @@ 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). -- 2.54.0