Contributing¶

We are always happy to see new contributors! If small or large, every contribution is welcome. Please follow these guidelines to ensure a smooth contribution process.

Prerequisites¶

Some technical knowledge for the following tools is required to get started with the project. If you are not familiar with them, please check out the documentation for each tool and make sure you have them installed.

Setting Up the Development Environment¶

  1. Clone the repository:

git clone https://github.com/pSpitzner/beets-flask
cd beets-flask

2.1 Install the dependencies (backend): We recommend using uv to manage the python dependencies but you can also use pip and a virtual environment of your choice.

cd backend
uv sync --all-extras --dev
source .venv/bin/activate
# or
pip install -e .[dev]

2.2 Install the dependencies (frontend): We use pnpm to manage the frontend dependencies. You may use any other package manager. On macOS you might want to run this command inside the container (see here).

cd frontend
pnpm install --frozen-lockfile

  1. Run the application in dev mode: Check the docker compose file and edit if necessary.

cd ../
# We recommend to create a copy of the docker compose file
cp ./docker/docker-compose.dev.yaml ./docker/docker-compose.dev-local.yaml
# Run the application after editing the docker compose file
docker compose -f ./docker/docker-compose.dev-local.yaml up --build

Install pre-commit hooks¶

We automatically check for code style and formatting issues using pre-commit hooks. To install the hooks, run the following command (optional):

pip install pre-commit
pre-commit install

Before Submitting a Pull Request¶

Run Ruff manually or use the pre-commit hooks to check for any issues. Additionally, run the tests to ensure that your changes do not break any existing functionality.

cd backend
# Code formatting and linting
ruff check
ruff lint
# Typing checks
mypy .
# Run the tests
pytest

Run eslint manually or use the pre-commit hooks to check for any issues. Additionally, run the tests to ensure that your changes do not break any existing functionality.

cd frontend
# Run eslint manually
pnpm lint
# Check the types
pnpm check-types

Submitting a Pull Request¶

Fork the repository and create a new branch for your changes. Feel free to follow this guide for more information on how to create a pull request. Once you are done we will review your changes as soon as possible. Please be patient, as we are a small team and may not be able to review your changes immediately.

Example docker compose¶

git clone https://github.com/pSpitzner/beets-flask.git ./beets_flask_dev
cd ./beets_flask_dev
mkdir local

Tweak docker/docker-compose.dev.yaml to your needs. Important is to live mount your repo folder:

services:
    beets-flask:
        container_name: beets-flask
        hostname: beets-container
        build:
            context: ..
            dockerfile: docker/Dockerfile
            target: dev
        image: beets-flask
        restart: unless-stopped
        ports:
            - "5001:5001"
            - "5173:5173"
        environment:
            USER_ID: 1000
            GROUP_ID: 1000
            LOG_LEVEL_BEETSFLASK: DEBUG
            LOG_LEVEL_OTHERS: WARNING
        volumes:
            - ../local/music/:/music/
            - ../local/config/:/config
            - ../:/repo/

After first launch you will need to install the frontend packages:

docker exec -it -u beetle beets-flask-dev bash
cd /repo/frontend
pnpm i

Check the viteserver at localhost:5173