diff --git a/README.rst b/README.rst
index 1cec0a6b70b2962c75e19e492d3300f0db7ea498..93281d26fb6abd65d0590183a416236a585b68e9 100644
--- a/README.rst
+++ b/README.rst
@@ -5,27 +5,107 @@ A self-hosted tribute to Grooveshark.com.
LICENSE: BSD
-Setting up a development environment (docker)
-----------------------------------------------
+Getting help
+------------
-First of all, pull the repository.
+We offer various Matrix.org rooms to discuss about funkwhale:
-Then, pull and build all the containers::
+- `#funkwhale:matrix.org <https://riot.im/app/#/room/#funkwhale:matrix.org>`_ for general questions about funkwhale
+- `#funkwhale-dev:matrix.org <https://riot.im/app/#/room/#funkwhale-dev:matrix.org>`_ for development-focused discussion
+
+Please join those rooms if you have any questions!
+
+Running the development version
+-------------------------------
+
+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://code.eliotberriot.com/funkwhale/funkwhale and clone the repository using SSH or HTTPS. Exemple using SSH::
+
+ git clone ssh://git@code.eliotberriot.com:2222/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. Therefor, when submitting Merge Requests, ensure you are merging on the develop branch.
+
+
+Working with docker
+^^^^^^^^^^^^^^^^^^^
+
+In developpement, 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 everytime, you can run this command before starting your work::
+
+ export COMPOSE_FILE=dev.yml
+
+
+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
- docker-compose -f dev.yml pull
-API setup
-^^^^^^^^^^
+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 proprely.
+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.
+
-You'll have apply database migrations::
+Development data
+^^^^^^^^^^^^^^^^
- docker-compose -f dev.yml run celeryworker python manage.py migrate
+You'll need at least an admin user and some artists/tracks/albums to work
+locally.
-And to create an admin user::
+Create an admin user with the following command::
- docker-compose -f dev.yml run celeryworker python manage.py createsuperuser
+ docker-compose -f dev.yml run --rm api python manage.py createsuperuser
+
+Injecting fake data is done by running the fllowing 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
+
+The previous command will create 25 artists with random albums, tracks
+and metadata.
Launch all services
@@ -33,18 +113,83 @@ Launch all services
Then you can run everything with::
- docker-compose up
+ docker-compose -f dev.yml up
+
+This will launch all services, and output the logs in your current terminal window.
+If you prefer to launch them in the background instead, use the ``-d`` flag, and access the logs when you need it via ``docker-compose -f dev.yml logs --tail=50 --follow``.
+
+Once everything is up, you can access the various funkwhale's components:
+
+- The Vue webapp, on http://localhost:8080
+- The API, on http://localhost:8080/api/v1/
+- The django admin, on http://localhost:8080/api/admin/
-The API server will be accessible at http://localhost:6001, and the front-end at http://localhost:8080.
Running API tests
-------------------
+^^^^^^^^^^^^^^^^^
+
+To run the pytest test suite, use the following command::
+
+ docker-compose -f dev.yml run --rm api pytest
+
+This is regular pytest, so you can use any arguments/options that pytest usually accept::
+
+ # get some help
+ docker-compose -f dev.yml run --rm api pytest -h
+ # Stop on first failure
+ docker-compose -f dev.yml run --rm api pytest -x
+ # Run a specific test file
+ docker-compose -f dev.yml run --rm api pytest tests/test_acoustid.py
+
+
+Running front-end tests
+^^^^^^^^^^^^^^^^^^^^^^^
+
+To run the front-end test suite, use the following command::
+
+ docker-compose -f dev.yml run --rm front yarn run unit
+
+We also support a "watch and test" mode were we continually relaunch
+tests when changes are recorded on the file system::
+
+ docker-compose -f dev.yml run --rm front yarn run unit-watch
+
+The latter is especially useful when you are debugging failing tests.
+
+.. note::
+
+ The front-end test suite coverage is still pretty low
+
+
+Stopping everything
+^^^^^^^^^^^^^^^^^^^
+
+Once you're down with your work, you can stop running containers, if any, with::
+
+ docker-compose -f dev.yml stop
+
+
+Removing everything
+^^^^^^^^^^^^^^^^^^^
+
+If you want to wipe your development environment completely (e.g. if you want to start over from scratch), just run::
+
+ docker-compose -f dev.yml down -v
+
+This will wipe your containers and data, so please be careful before running it.
-Everything is managed using docker and docker-compose, just run::
+You can keep your data by removing the ``-v`` flag.
- ./api/runtests
-This bash script invoke `python manage.py test` in a docker container under the hood, so you can use
-traditional django test arguments and options, such as::
+Typical workflow for a merge request
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- ./api/runtests funkwhale_api.music # run a specific app test
+0. Fork the project if you did not already or if you do not have access to the main repository
+1. Checkout the development branch and pull most recent changes: ``git checkout develop && git pull``
+2. Create a dedicated branch for your work ``42-awesome-fix``. It is good practice to prefix your branch name with the ID of the issue you are solving.
+3. Work on your stuff
+4. Commit small, atomic changes to make it easier to review your contribution
+5. Add a changelog fragment to summarize your changes: ``echo "Implemented awesome stuff (#42)" > changes/changelog.d/42.feature"``
+6. Push your branch
+7. Create your merge request
+8. Take a step back and enjoy, we're really grateful you did all of this and took the time to contribute!
diff --git a/changes/changelog.d/123.doc b/changes/changelog.d/123.doc
new file mode 100644
index 0000000000000000000000000000000000000000..679a0b8aff7775ef9863270513aae25c972b0fd9
--- /dev/null
+++ b/changes/changelog.d/123.doc
@@ -0,0 +1 @@
+Up-to-date and complete development and contribution instructions in README.rst (#123)