Getting Started

Warning

pre-condition: run installation guide first before you start working on this section.

Cause MrMap is full dockerized, the development of it is priciple possible on any operating system. Feel free to use the development ide of your choice.

We provide configuration files for pycharm and vscode.

Note

Cause everthing is running with docker, all management commands need to be called inside the corresponding container. See Running Management Commands

Branch structure

The MrMap project utilizes three persistent git branches to track work:

  • master - Serves as a snapshot of the current stable release

  • develop - Tracks work on an upcoming new minor release

  • feature - Tracks work on an upcoming new feature

Typically, you’ll base pull requests off of the develop branch, or off of feature if you’re working on a new major release. Never merge pull requests into the master branch, which receives merged only from the develop branch.

Enable Pre-Commit Hooks

MrMap ships with a git pre-commit hook script that automatically checks for style compliance and missing database migrations prior to committing changes. This helps avoid erroneous commits that result in CI test failures. You are encouraged to enable it by creating a link to scripts/git-hooks/pre-commit:

$ cd .git/hooks/
$ ln -s ../../scripts/git-hooks/pre-commit

Running management commands

Note

As pre condition MrMap application must be running.

$ docker-compose -f ./docker-compose.yml up --build

Note

The prefix of started docker container name is always the name of the root folder where the docker-compose file lives in. In examples below, my root folder name is mrmap.

Running echo

$ docker exec -it mrmap_gunicorn_1 echo "I'm inside the container!"

Running makemigrations

$ docker exec -it mrmap_gunicorn_1 python /opt/mrmap/manage.py makemigrations

Running migrate

$ docker exec -it mrmap_gunicorn_1 python /opt/mrmap/manage.py migrate

Running makemessages

Makemessages should run local by calling:

$ python manage.py makemessages --locale=de

Running compilemessages

Compilemessages should run local by calling:

$ python manage.py compilemessages --locale=de

Running Tests

Throughout the course of development, it’s a good idea to occasionally run MrMap’s test suite to catch any potential errors. Tests are run using the test management command:

$ docker-compose -f ./docker-compose.yml -f ./docker-compose.dev.yml up --build test

In cases where you haven’t made any changes to the database (which is most of the time), you can append the --keepdb argument to this command to reuse the test database between runs. This cuts down on the time it takes to run the test suite since the database doesn’t have to be rebuilt each time. (Note that this argument will cause errors if you’ve modified any model fields since the previous test run.)

$ docker-compose -f ./docker-compose.yml -f ./docker-compose.dev.yml up --build test --keepdb

Test documentation builds properly

Warning

You need to have installed all python dependencies locally first. pip3 install -r ./backend/requirements.txt && pip3 install -r ./backend/docs/requirements.txt

$ sphinx-multiversion docs/source docs/build/html -b linkcheck

The documentation should be successfully build in the docs/build folder. Open the docs/build/index.html to test it.

Submitting Pull Requests

Once you’re happy with your work and have verified all steps described in DoD submit a pull request to the MrMap repo to propose the changes. Always provide descriptive (but not excessively verbose) commit messages. When working on a specific issue, be sure to reference it.

$ git commit -m "Closes #1234: Add wms support"
$ git push origin

Be sure to provide a detailed accounting of the changes being made and the reasons for doing so.

Once submitted, a maintainer will review your pull request and either merge it or request changes. If changes are needed, you can make them via new commits to your branch: The pull request will update automatically.

Note

Remember, pull requests are entertained only for accepted issues. If an issue you want to work on hasn’t been approved by a maintainer yet, it’s best to avoid risking your time and effort on a change that might not be accepted.