Initial public release

2026-04-03 15:53:00 +01:00
commit a99c738164
679 changed files with 108326 additions and 0 deletions
@@ -0,0 +1,78 @@
+# Contributing to MusicSeerr
+
+Thanks for your interest. Bug reports, feature requests, and pull requests are all welcome.
+
+## Reporting Bugs
+
+Use the [bug report template](https://github.com/habirabbu/musicseerr/issues/new?template=bug.yml). 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](https://github.com/habirabbu/musicseerr/issues/new?template=feature.yml). 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:
+
+```bash
+cd backend
+pip install -r requirements-dev.txt
+uvicorn main:app --reload --port 8688
+```
+
+Frontend:
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+### Running Tests
+
+```bash
+make backend-test    # backend suite
+make frontend-test   # frontend suite
+make test            # both
+```
+
+Frontend browser tests use Playwright. Install the browser first:
+
+```bash
+make frontend-browser-install
+```
+
+## Pull Requests
+
+1. Fork the repo and create a branch from `main`.
+2. Give your branch a descriptive name: `fix-scrobble-timing`, `feature-playlist-export`, etc.
+3. If you're fixing a bug, mention the issue number in the PR description.
+4. Make sure tests pass before submitting.
+5. 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](https://discord.gg/f98bFfsPuB) or start a [GitHub Discussion](https://github.com/habirabbu/musicseerr/discussions).