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