CONTRIBUTING.rst

Contribute to Funkwhale development

First of all, thank you for your interest in the project! We really appreciate the fact that you're about to take some time to read this and hack on the project.

This document will guide you through common operations such as:

• Setup your development environment
• Working on your first issue
• Writing unit tests to validate your work
• Submit your work

A quick path to contribute on the front-end

The next sections of this document include a full installation guide to help you setup a local, development version of Funkwhale. If you only want to fix small things on the front-end, and don't want to manage a full development environment, there is another way.

As the front-end can work with any Funkwhale server, you can work with the front-end only, and make it talk with an existing instance (like the demo one, or you own instance, if you have one).

If even that is too much for you, you can also make your changes without any development environment, and open a merge request. We will be able to review your work easily by spawning automatically a live version of your changes, thanks to Gitlab Review apps.

Setup front-end only development environment

1. Clone the repository:

   git clone ssh://git@dev.funkwhale.audio/funkwhale/funkwhale.git
   cd funkwhale
   cd front

2. Install nodejs and yarn

3. Install the dependencies:

   yarn install

4. Compile the translations:

   yarn i18n-compile

5. Launch the development server:

   # this will serve the front-end on http://localhost:8000/front/
   VUE_PORT=8000 yarn serve

6. Make the front-end talk with an existing server (like https://demo.funkwhale.audio or https://open.audio), by clicking on the corresponding link in the footer

7. Start hacking!

Setup your development environment

If you want to fix a bug or implement a feature, you'll need to run a local, development copy of funkwhale.

We provide a docker based development environment, which should be both easy to setup and work similarly regardless of your development machine setup.

Instructions for bare-metal setup will come in the future (Merge requests are welcome).

Installing docker and docker-compose

This is already cover in the relevant documentations:

• https://docs.docker.com/install/
• https://docs.docker.com/compose/install/

Cloning the project

Visit https://dev.funkwhale.audio/funkwhale/funkwhale and clone the repository using SSH or HTTPS. Example using SSH:

git clone ssh://git@dev.funkwhale.audio/funkwhale/funkwhale.git
cd funkwhale

A note about branches

Next release development occurs on the "develop" branch, and releases are made on the "master" branch. Therefore, when submitting Merge Requests, ensure you are merging on the develop branch.

Working with docker

In development, we use the docker-compose file named dev.yml, and this is why all our docker-compose commands will look like this:

docker-compose -f dev.yml logs

If you do not want to add the -f dev.yml snippet every time, you can run this command before starting your work:

export COMPOSE_FILE=dev.yml

Creating your env file

We provide a working .env.dev configuration file that is suitable for development. However, to enable customization on your machine, you should also create a .env file that will hold your personal environment variables (those will not be commited to the project).

Create it like this:

touch .env

Create docker network

Create the federation network:

docker network create federation

Building the containers

On your initial clone, or if there have been some changes in the app dependencies, you will have to rebuild your containers. This is done via the following command:

docker-compose -f dev.yml build

Database management

To setup funkwhale's database schema, run this:

docker-compose -f dev.yml run --rm api python manage.py migrate

This will create all the tables needed for the API to run properly. You will also need to run this whenever changes are made on the database schema.

It is safe to run this command multiple times, so you can run it whenever you fetch develop.

Development data

You'll need at least an admin user and some artists/tracks/albums to work locally.

Create an admin user with the following command:

docker-compose -f dev.yml run --rm api python manage.py createsuperuser

Injecting fake data is done by running the following script:

artists=25
command="from funkwhale_api.music import fake_data; fake_data.create_data($artists)"
echo $command | docker-compose -f dev.yml run --rm api python manage.py shell -i python