Adapt agent guidance and supporting docs for BeatGlow
This commit is contained in:
5 files changed
+154
-1
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user