Contributing to MusicSeerr

Thanks for your interest. Bug reports, feature requests, and pull requests are all welcome.

Reporting Bugs

Use the bug report template. Include your MusicSeerr version, steps to reproduce, and relevant logs from docker compose logs musicseerr. The more detail you give, the faster things get fixed.

Requesting Features

Use the feature request template. Check existing issues first to avoid duplicates.

Development Setup

The backend is Python 3.13 with FastAPI. The frontend is SvelteKit with Svelte 5, Tailwind CSS, and daisyUI.

Prerequisites

Python 3.13+
Node.js 22+
Docker (for building the full image)

Running Locally

Backend:

cd backend
pip install -r requirements-dev.txt
uvicorn main:app --reload --port 8688

Frontend:

cd frontend
npm install
npm run dev

Running Tests

make backend-test    # backend suite
make frontend-test   # frontend suite
make test            # both

Frontend browser tests use Playwright. Install the browser first:

make frontend-browser-install

Pull Requests

Fork the repo and create a branch from main.
Give your branch a descriptive name: fix-scrobble-timing, feature-playlist-export, etc.
If you're fixing a bug, mention the issue number in the PR description.
Make sure tests pass before submitting.
Keep changes focused. One PR per fix or feature.

Code Style

Backend: strong typing, async/await, no blocking I/O in async contexts.
Frontend: strict TypeScript, no any. Named exports. Async/await only.
Use existing design tokens (primary, secondary, etc.) for colours, not hardcoded values.
Run npm run lint and npm run check in the frontend before submitting.

AI-Assisted Contributions

If you used AI tools (Copilot, ChatGPT, Claude, etc.) to write code in your PR, please mention it. This isn't a problem and won't get your PR rejected, but it helps reviewers calibrate how much scrutiny to apply. A quick note like "Claude helped with the caching logic" is enough.

You're still responsible for understanding and testing the code you submit.

Questions?

Open a thread in Discord or start a GitHub Discussion.

2.4 KiB Raw Blame History