Contributing

Contributing

Trove is intentionally small, practical, and read-only.

If you contribute, preserve that shape.

Project principles

• Read-only first.
• Simple beats clever.
• SQLite is fine until there is a real reason it is not.
• Agents push. The server does not control agents.
• Platform credentials should be least-privilege.
• Avoid notification spam.
• Do not turn Trove into a management plane.

Before changing code

Run:

make fmt
make vet
make test

For bigger changes, also run a local server and at least one real agent.

Adding an agent

A new agent should:

1. use internal/agentkit
2. implement Collector
3. map platform objects into pkg/model
4. use read-only platform APIs
5. document required credentials
6. include troubleshooting notes for common permission failures

Avoid bringing server/store dependencies into agent code.

Changing the report model

Changes to pkg/model affect agents and server.

Think through:

• compatibility with older agents
• validation behaviour
• JSON field names
• whether the field belongs in the common model or platform metadata

Changing alerts

Be careful with alert state.

Alerts must avoid:

• repeat spam for the same incident
• missing resolved notices
• boot floods
• treating every deploy as an incident
• losing delivery state during cooldown or reconnects

Add regression tests for edge cases.

Changing the database

Schema changes need migrations.

Do not rely on manual SQLite changes.

Preserve existing data where practical.

Documentation expectations

Update docs when changing:

• install steps
• environment variables
• platform credentials
• alert behaviour
• API shapes
• release workflow
• security posture

Docs should be practical. Include the command someone will actually run and the mistake they are likely to make.