Thanks for your interest in contributing to Explo.
Explo is maintained by a small number of active contributors with limited time, so every change is considered not only for its usefulness, but also for its maintenance cost.
Explo started as a simple personal Go script in 2023: fetch recommendations from ListenBrainz, find the tracks on YouTube, and create playlists in Navidrome (Subsonic). It was originally intended to run as a single binary on a server.
While Explo has grown significantly since then, its core goal has remained the same: automated music discovery for self-hosted music systems.
Explo is designed to be a set-and-forget solution. Once configured, it should run with minimal user intervention, continuously requesting music and creating playlists. Optional interaction is acceptable, but automation remains the default. Features that cannot reasonably fit this automation-first approach may be rejected.
This philosophy also applies to Explo's development. The codebase should be as close to set-and-forget as the application itself. Changes should avoid introducing unnecessary maintenance, manual intervention, or complexity for maintainers.
The project prioritizes:
- Reliability over feature count
- Automation over manual workflows
- Compatibility across supported platforms
- Long-term maintainability
Not every useful feature belongs in Explo. Features may be declined when they do not align with the project's goals, even if they solve a legitimate use case.
Compatibility is a priority.
Changes should avoid breaking existing configurations, Docker deployments or supported integrations whenever possible. If a breaking change is necessary, discuss it first and provide a clear migration path.
Please discuss changes before beginning work on them.
- Check existing issues first
- If an issue already exists, comment there before starting work
- If the idea involves a specific music system, please try to check if it can be implemented on other supported systems as well
Opening a pull request without prior discussion may result in it being rejected.
Wait for maintainer feedback before investing significant work in a new feature.
Pull requests are easier to review when they solve one problem at a time.
Good examples include:
- Bug fixes
- Small, well-scoped features
- Refactors that solve a specific maintenance issue
If a pull request contains multiple related fixes or features, use a title that reflects the overall change rather than a single problem.
You do not need to know every part of the codebase, but you should understand the code you work with and systems you modify.
Before submitting:
- Test the implementation on every supported system affected by your changes
- Make sure existing functionality continues to work unless the change intentionally modifies it
AI-driven development is discouraged.
Examples include:
- Most or all code generated by LLM agents
- Submitting generated code without understanding how it works or accounting for platform limitations
AI-assisted development is allowed when used as a supporting tool.
Examples include:
- Rubber ducking
- Explaining unfamiliar parts of the codebase
- Generating small helper functions
Contributors are responsible for understanding and testing all submitted code.
Large AI-generated implementations or refactors that the author cannot explain, verify, or maintain will be rejected.