chore: update README

Include information about development setup.

Co-authored by: Kasimir Uihlein <kuihlein@mailbox.org>

README.md

@@ -2,29 +2,105 @@
 
 [![Build Status](https://jenkins.merten.dev/buildStatus/icon?job=gitea%2Fkompass%2Fmain)](https://jenkins.merten.dev/job/gitea/job/kompass/job/main/)
 
-This repository has the purpose to develop a webapplication that can be used by
+Kompass is an administration platform designed for local sections of the Young German Alpine Club. It provides
-JDAV to send newsletters, manage user lists and keep material lists up to date.
+tools to contact and (automatically) manage members, groups, material, excursions and statements.
-As this repository is also meant to be a base for exchange during development, feel free
-to contribute ideas in form of edits to this README, issues, landmarks, projects, wiki entries, ...
 
-# Docker
+For more details on the features, see the (German) [documentation](https://jdav-hd.de/static/docs/index.html).
 
-In the `docker` subfolder, there are `docker-compose.yaml`s for development and production use. For the development
+# Contributing
-version, no further setup is needed.
 
-# Production
+Any form of contribution is appreciated. If you found a bug or have a feature request, please file an
+[issue](https://git.jdav-hd.merten.dev/digitales/kompass/issues). If you want to help with the documentation or
+want to contribute code, please open a [pull request](https://git.jdav-hd.merten.dev/digitales/kompass/pulls).
 
-In production, the docker setup needs an external database. The exact access credentials are configured in the respective
+The following is a short description of the development setup and an explanation of the various
-docker.env files.
+branches.
 
-# Useful stuff
+## Development setup
 
-## Reset database for certain app
+The project is run with `docker` and all related files are in the `docker/` subfolder. Besides the actual Kompass
+application, a database (postgresql) and a broker (redis) are setup and run in the docker container. No
+external services are needed for running the development container.
 
-The following can be useful in case that automatic migrations throw errors.
+### Initial installation
 
-1. delete everything in the migrations folder except for __init__.py.
+A working `docker` setup (with `docker compose` support) is required. For installation instructions see the
-2. drop into my MySQL console and do: DELETE FROM django_migrations WHERE app='my_app'
+[docker manual](https://docs.docker.com/engine/install/).
-3. while at the MySQL console, drop all of the tables associated with my_app.
+
-4. re-run ./manage.py makemigrations my_app - this generates a 0001_initial.py file in my migrations folder.
+1. Clone the repository and change into the directory of the repository.
-5. run ./manage migrate my_app - I expect this command to re-build all my tables, but instead it says: "No migrations to apply."
+
+2. Fetch submodules
+   ```bash
+   git submodule update --init
+   ```
+
+3. Prepare development environment: to allow automatic rebuilding upon changes in the source,
+   the owner of the `/app/jdav_web` directory in the docker container must agree with
+   your user. For this, make sure that the output of `echo UID` and `echo UID` is not empty. Then run
+   ```bash
+   export GID=${GID}
+   export UID=${UID}
+   ```
+
+4. Start docker
+   ```bash
+   cd docker/development
+   docker compose up
+   ```
+   This runs the docker in your current shell, which is useful to see any log output. If you want to run
+   the development server in the background instead, use `docker compose up -d`.
+
+   During the initial run, the container is built and all dependencies are installed which can take a few minutes.
+   After successful installation, the Kompass initialization runs, which in particular sets up all tables in the
+   database.
+
+5. Setup admin user: in a separate shell, while the docker container is running, run
+   ```bash
+   cd docker/development
+   docker compose exec master bash -c "cd jdav_web && python3 manage.py createsuperuser"
+   ```
+   This creates an admin user for the administration interface.
+
+### Development
+
+If the initial installation was successful, you can start developing. Changes to files cause an automatic
+reload of the development server. If you need to generate and perform database migrations or generate locale files,
+use
+```
+cd docker/development
+docker compose exec master bash
+cd jdav_web
+```
+This starts a shell in the container, where you can execute any django maintenance commands via
+`python3 manage.py <command>`. For more information, see the [django documentation](https://docs.djangoproject.com/en/4.0/ref/django-admin).
+
+### Testing
+
+To run the tests, you can use the docker setup under `docker/test`.
+
+### Known Issues
+
+- If the `UID` and `GID` variables are not setup properly, you will encounter the following error message
+  after running `docker compose up`.
+
+  ```bash
+  => ERROR [master 6/7] RUN groupadd -g  fritze && useradd -g  -u  -m -d /app fritze                                                                                                                0.2s
+  ------
+  > [master 6/7] RUN groupadd -g  fritze && useradd -g  -u  -m -d /app fritze:
+  0.141 groupadd: invalid group ID 'fritze'
+  ------
+  failed to solve: process "/bin/sh -c groupadd -g $GID $USER && useradd -g $GID -u $UID -m -d /app $USER" did not complete successfully: exit code: 3
+  ```
+  In this case repeat step 3 above.
+
+## Organization and branches
+
+The stable development happens on the `main` branch for which only maintainers have write access. Any pull request
+should hence be targeted at `main`. Regularly, the production instances are updated to the latest `main` version,
+in particular these are considered to be stable.
+
+If you have standard write access to the repository, feel free to create new branches. To make organization
+easier, please indicate your username in the branch name.
+
+The `testing` branch is deployed on the development instances. No development should happen there, this branch
+is regularly reset to the `main` branch.