Contributing
Report a problem
Section titled “Report a problem”Include the application revision, Navidrome version, deployment method, the steps to reproduce, and the result you expected. Add relevant sanitized logs. For imports, name the source and whether the failure occurs during connection, planning, download, or sync.
Keep credentials and private music out of reports. A small reproducible example is more useful than a full production configuration.
Change code
Section titled “Change code”Set up local development and work on a branch. Keep the change focused on one problem, and explain the resulting behavior in the pull request.
The project’s tests are end-to-end business scenarios at the bot boundary. They run the real database, Navidrome, filesystem, and ffmpeg; HTTP doubles stand in for Telegram and external providers. For behavior changes, write an observable scenario using Arrange, Act, Assert and a failing test before the implementation. Avoid unit tests that only repeat a use case’s internals.
The installer has its own scenarios in e2e/installer: they run the installer with typed answers against real Docker, Navidrome, and Caddy, with stand-ins for the bot and Telegram. Unit tests are kept for its pure text edits only, the Caddyfile block and config.toml merging, where a scenario per edge case would be slow.
Run just test, just lint, and just fmt for Go changes. Mention which checks ran and any check you could not complete. Do not mark a blocked check as passed.
CI runs formatting and lint checks, go vet, module verification, workflow checks with actionlint and zizmor, spelling with typos, secret scanning with Gitleaks, documentation checks, the installer tests, and the complete end-to-end suite. Run static checks locally with just lint and tests with just test. Every release must pass the same checks before its Docker image is published. Coverage counts the application and installer packages the scenarios exercise. On master, the total goes to the README badge through the badges branch.
Add an integration
Section titled “Add an integration”Check the provider interfaces and current Zvuk implementation before choosing a design. A source can support only some capabilities; distinguish collection metadata, audio download, and sync.
Cover connection failure, unavailable tracks, duplicates, quotas, and later collection changes in business-scenario tests. Update the source table and the provider table in the README, add a setup guide, and describe the exact sync behavior and credentials it requires.
Maintainers set up checks, coverage, and image publishing with the CI and release guide.
Documentation
Section titled “Documentation”The site is built with Starlight from docs/src/content/docs. Run npm ci and npm run check in docs, or just docs, before opening a pull request. Use the terms from the glossary. Instead of version numbers, write the placeholders release_tag, release_version, navidrome_version, or postgres_version in double curly braces. The build fills them in from the latest release and deploy/compose.yml.
License
Section titled “License”beatstash is licensed under MIT. Contributions are included under the project’s license.