Development

Pre-Commit Hooks

Every time you clone this project the following command should be the first thing you do afterwards to enable all active hooks. For more information about pre-commit hooks see their homepage.

pre-commit install

From time to time it might be necessary to update the pre-commit hooks, which can be accomplished by running

pre-commit autoupdate

Style-Guide

Python

Please refer to Google’s Python Style Guide.

The only deviation from this style guide is the increased line limit of 88 characters, the default setting of the Black formatter.

This project hosts a PyLint configuration file to ensure the defined coding style and quality. Furthermore, Black is enabled as a pre-commit hook and will format all files before a commit, if configured correctly as described in Pre-Commit Hooks. PyLint can be configured as an external tool in most IDEs. Start it from the root directory of ForTrace, so the configuration file is automatically read in. Specify the file to be checked afterwards.

pylint file/to/check

Alternatively, it is also possible to read whole directories and lint the files.

find . -type f -name "*.py" | xargs pylint --rcfile pylintrc

Warning

Currently, there is no docstring formatter that supports Google docstrings.

Jupyter Notebooks

Jupyter Notebooks are used to run evaluations on executed ForTrace++ scenarios.

Two pre-commit hooks are concerned with this file type:

1. jupyter-nb-clear-output is used to clear all output of a Notebook before it is committed.

2. black-jupyter is used to format a Notebook before it is committed. Make sure to install the .[dev] dependencies.

rST

reStructuredText files are formatted with docstrfmt through a pre-commit hook. It can be installed as a Python package and is included in the .[docs] group of this project.

Follow the instructions in the docstrfmt’s readme, to integrate it with your IDE and enable formatting on-save.

Git

Git is used for version control.

Commit Messages

The commit messages must adhere to the Conventional Commits Specification. This standard is enforced using Commitizen as a pre-commit hook. It is advised to read and understand this standard.

The following section is only a short part of the whole standard.

A commit message has to be structured as follows:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

The type must be one of the following (taken from Angular Guidelines:

Keyword	Description
build	Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
ci	Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
docs	Documentation only changes
feat	A new feature
fix	A bug fix
perf	A code change that improves performance
refactor	A code change that neither fixes a bug nor adds a feature
style	Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
test	Adding missing tests or correcting existing tests

Branching

This convention is taken from this article. A git branch should start with one of the following categories:

Keyword	Description
feature	Adding, Refactoring Or Removing A Feature
bugfix	Fixing A Bug
hotfix	Changing Code With A Temporary Solution And/or Without Following The Usual Process (usually Because Of An Emergency)
test	Experimenting Outside Of An Issue/ticket

The prefix is followed by /T-<Issue no.> and the issue title. Git is then able to associate the branch with a given issue.

Python Packages

If available, please use a pip-requirements file for your desired Python version from the root directory of this project. This file contains pinned package versions and will most likely result in a more deterministic working version of ForTrace++. This minimizes bugs related to different package versions.

Update packages

Make sure you have installed the pip-tools package, available through the dev optional dependencies group. With the following command you can create a new requirements file with updated package versions. Afterwards run pip to install the now updated packages.

pip-compile --strip-extras -U

Please run the tests suite afterwards, to ensure everything is still working as expected.

Testing

Testing is done with pytest. Please follow the conventions for Python test discovery as described in the pytest documentation.

For a more detailed guide of pytest refer to the documentation or more specifically to the usage guide.

In case you want to manually run all defined tests, call pytest from the project’s root directory. pytest reads its configuration from the pyproject.toml file.

pytest

You might want to in- or exclude specific markers, which can be achieved by using the -m option.

pytest -m <name of marker>
pytest -m "not <name of marker>"

Installation

If you plan to edit files in the source tree due to development, remember to install ForTrace in development mode, so that changes to the source code will immediately affect the installed package without needing to re-install:

pip install --editable ".[dev,test]"

Using a Conda Environment

You might want to use a Conda environment, instead of a regular venv. This can be easily achieved, by following the steps below.

Miniconda

Install Miniconda following the instructions given by Anaconda.

After you have successfully installed Miniconda, create the environment.

conda create -n fortrace
conda activate fortrace
conda install pip
FILE_SUFFIX=$(python --version | grep -oP '(?<=Python )\d+\.\d+' | sed 's/\./_/g')
pip install -r requirements_lock_$FILE_SUFFIX.txt

Set the environment variable to include the src directory of ForTrace++.

conda env config vars set "PYTHONPATH=$PYTHONPATH:/path/to/fortrace_root/src" -n fortrace