Merge pull request 'Add BeatGlow agent instructions and feature-branch workflow' (#2) from chore/agent-branch-policy into main
Reviewed-on: #2
This commit was merged in pull request #2.
This commit is contained in:
commit
e4c2060422
5 files changed
+158
No files matched your search
@@ -16,6 +16,8 @@
|
|||||||
|
|
||||||
!README.md
|
!README.md
|
||||||
!LICENSE
|
!LICENSE
|
||||||
|
!/AGENTS.md
|
||||||
|
!/docs/agents/*.md
|
||||||
|
|
||||||
# README screenshots and wiring illustrations
|
# README screenshots and wiring illustrations
|
||||||
!/asset/image/beatglow-*.gif
|
!/asset/image/beatglow-*.gif
|
||||||
|
|||||||
@@ -0,0 +1,100 @@
|
|||||||
|
# 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`.
|
||||||
|
- 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.
|
||||||
|
- 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.
|
||||||
|
- 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 `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.
|
||||||
|
|
||||||
|
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.
|
||||||
@@ -0,0 +1,19 @@
|
|||||||
|
# Coding conventions
|
||||||
|
|
||||||
|
- 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.
|
||||||
|
- 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.
|
||||||
@@ -0,0 +1,19 @@
|
|||||||
|
# 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.
|
||||||
@@ -0,0 +1,18 @@
|
|||||||
|
# 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.
|
||||||
Reference in new issue
Block a user