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 <https://pre-commit.com/>`_.

.. code-block:: console

    pre-commit install

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

.. code-block:: console

    pre-commit autoupdate

Style-Guide
-----------

Python
~~~~~~

Please refer to `Google's Python Style Guide
<https://google.github.io/styleguide/pyguide.html>`_.

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.

.. code-block:: console

    pylint file/to/check

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

.. code-block:: console

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

.. warning::

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

Jupyter Notebooks
~~~~~~~~~~~~~~~~~

`Jupyter Notebooks <https://jupyter.org/>`_ 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
<https://github.com/LilSpazJoekp/docstrfmt>`_, 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
<https://www.conventionalcommits.org/en/v1.0.0/>`_. This standard is enforced using
`Commitizen <https://github.com/commitizen-tools/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
<https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#type>`_:

======== ==============================================================================
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
<https://dev.to/varbsan/a-simplified-convention-for-naming-branches-and-commits-in-git-il4>`_.
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.

.. code-block:: console

    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
<https://docs.pytest.org/en/7.1.x/explanation/goodpractices.html#conventions-for-python-test-discovery>`_.

For a more detailed guide of pytest refer to the `documentation
<https://docs.pytest.org/en/latest/index.html>`_ or more specifically to the `usage
guide <https://docs.pytest.org/en/latest/how-to/usage.html>`_.

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.

.. code-block:: console

    pytest

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

.. code-block:: console

    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:

.. code-block:: console

    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
<https://docs.anaconda.com/miniconda/miniconda-install/>`_ given by Anaconda.

After you have successfully installed Miniconda, create the environment.

.. code-block:: console

    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++.

.. code-block:: console

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