Trails

A web app for easily organizing your mountain adventures.

1. Table of contents

• 1. Table of contents
• 2. Development environment setup
  • 2.1. Miniconda
  • 2.2. Install trails CLI
  • 2.3. Developing with a dockerized Postgresql database
• 3. Additional installations before contributing
  • 3.1. Pre-commit hooks
  • 3.2. Commitizen
• 4. Release strategy from development to main branch

2. Development environment setup

The following steps will guide you through the installation procedure.

2.1. Miniconda

is required for creating the development environment (it is suggested to install Miniconda).

From terminal navigate to the repository base directory.
Use the following command in your terminal to create an environment named trails-app.

conda env create -f environment.yml

Activate the new Conda environment with the following command.

conda activate trails-app

2.2. Install trails CLI

The CLI is distributed with setuptools instead of using Unix shebangs.
It is a very simple utility to initialize and delete the app database. There are different use cases:

• Create/delete an sqlite database for local debug
• Initialize/drop tables inside a contanerized Postgresql database
• Initialize/drop tables Heroku's Postgresql add-on

Use the following command for generating the CLI executable from the setup.py file, it will install your package locally.

pip install .

If you want to make some changes to the source code it is suggested to use the following option.

pip install --editable .

It will just link the package to the original location, basically meaning any changes to the original package would reflect directly in your environment.

Now you can activate the Conda environment and access the CLI commands directly from the terminal (without using annoying shebangs or prepending python to run your CLI calls).

Test that everything is working correctly with the following commands.

trails --version
trails --help

Note:
To create the sqlite database and run the app locally, use the flag --sqlite-test-db when calling db commands.
In addition an environment variable named FLASK_TEST_DBshall exist for Flask to work correctly with sqlite.

Create the local sqlite database with:

export FLASK_TEST_DB=true && trails --sqlite-test-db db init

And then launch the app:

python -m trails_app flask=sqlite server=sqlite

Delete the local sqlite database with:

export FLASK_TEST_DB=true && trails --sqlite-test-db db delete && unset FLASK_TEST_DB

2.3. Developing with a dockerized Postgresql database

Since this app is hosted on Heroku (by using a Docker container) the Postgresql Addon is used.
After an initial development phase supported by an sqlite database, I moved to a dockerized Postgresql database.

Look inside the makefile to see the configuration options I selected for this scope.

To run a container with a Postgresql database for your development environment, you have to install Docker and download the official Postgresql image.

My suggestion is to build the two images from the docker-compose.yaml and then run only the database instance to have a containerized Postgresql database accessible from your local environment.

First build the two images, one for each container:

• web for the app
• db for the postgresql database

From the project directory call the following make commands.

make up-build

The two images are built and the two containers are started.
Since you need only the database for development pourposes you can turn them down.

make down

Then start the only the database container.

make run-db

Do not forget to initialize the database or the app will complain because tables are not there.

trails db init

This set up (with only the database running inside a container) will allow you to see changes on html and Python files without rebuilding Docker images.
All you have to do is start the web server locally with Python.

python -m trails_app

The app will be available at localhost:5000.

Note:
You can also use make up to access the app from the container system build by Docker compose. However, in this case you have to rebuild the images (with make up-build) every time you edit the codebase to see changes in place.

3. Additional installations before contributing

Before contributing please create the pre-commit and commitizen environments.

cd requirements
conda env create -f pre-commit.yml
conda env create -f commitizen.yml

3.1. Pre-commit hooks

Then install the precommit hooks.

conda activate pre-commit
pre-commit install
pre-commit autoupdate

Optionally run hooks on all files.

pre-commit run --all-files

3.2. Commitizen

The Commitizen hook checks that rules for conventional commits are respected in commits messages. Use the following command to enjoy Commitizen's interactive prompt.

conda activate commitizen
cz commit

cz c is a shorther alias for cz commit.

4. Release strategy from development to main branch

In order to take advantage of Commitizen bump command follow this guideline.

First check that you are on the correct branch.

git checkout main

Then start the merge process forcing it to stop before commit (--no-commit) and without using the fast forward strategy (--no-ff).

git merge development --no-commit --no-ff

Check that results match your expectations then commit (you can leave the default message).

git commit

Now Commitizen bump command will add an additional commit with updated versions to every file listed inside pyproject.toml.

cz bump --no-verify

You can now merge results of the release process back to the development branch.

git checkout development
git merge main --no-ff

Use "update files from last release" as commit message.