Makefile
========

Why Makefiles?
--------------

We're using `Makefiles <https://en.wikipedia.org/wiki/Makefile>`_ in our projects because we want to have a clear & simple interface for all common actions. This interface is used for:

- Preparing the local development environment
- Running local tasks during the development
- Running the same tasks in CI/CD pipelines

There might be alternative solutions out there, but Makefiles and ``make`` do the job just fine and they're widely accepted. Makefiles can get messy, but all of our Makefiles are and will always be simple.

.. important::

    It is important that tasks in the CI/CD pipelines are executed similar to the tasks executed locally (e.g. for testing), thus the unified interface.
    Most of the `GitLab CI files <https://git.confirm.ch/confirm/gitlab-ci>`_ use exactly these `Makefiles`_.

Common targets
--------------

Usually most of our projects include `Makefiles`_ which use common targets.

Prepare development environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Preparing the development environment for most of our Python projects & packages is quite similar and looks like this:

.. code-block:: bash

    make venv
    source .venv/bin/activate
    make develop

Clean targets
~~~~~~~~~~~~~

+-----------------+--------------------------------------------------------------+
|      Target     |                            Usage                             |
+=================+==============================================================+
| ``clean``       | Clean all downloaded & built files                           |
+-----------------+--------------------------------------------------------------+
| ``clean-cache`` | Clean cache files, e.g. Python's ``*.pyc`` & ``__pycache__`` |
+-----------------+--------------------------------------------------------------+
| ``clean-test``  | Clean test (configuration) files                             |
+-----------------+--------------------------------------------------------------+
| ``clean-build`` | Clean built files, e.g. the ``build/`` directory             |
+-----------------+--------------------------------------------------------------+
| ``clean-venv``  | Clean the `Python venv`_                                     |
+-----------------+--------------------------------------------------------------+

Install targets
~~~~~~~~~~~~~~~

+--------------------+-------------------------------------------------------------------------------+
|       Target       |                                     Usage                                     |
+====================+===============================================================================+
| ``venv``           | Create a `Python venv <https://docs.python.org/3/library/venv.html>`_         |
+--------------------+-------------------------------------------------------------------------------+
| ``develop``        | Install the project or package for development (*incl. all dev requirements*) |
+--------------------+-------------------------------------------------------------------------------+
| ``develop-python`` | Install the Python dependencies for the project or package for development    |
+--------------------+-------------------------------------------------------------------------------+
| ``develop-node``   | Install the Node dependencies for the project or package for development      |
+--------------------+-------------------------------------------------------------------------------+
| ``install``        | Install the project or package                                                |
+--------------------+-------------------------------------------------------------------------------+

.. hint::

    You can also install dependent Python packages locally without depending on the :ref:`PyPi Server`.
    Simply clone the Git repository of the dependent Python package and use one of the following commands **while the project's Python venv is active**:

    .. code-block:: bash

        # Install Python package for the use in a project.
        make -C {local Git repository} install

        # Develop on a Python package while in use in a project (i.e. library development).
        make -C {local Git repository} develop

.. hint::

    In case you're not in our private networks, installing PyPi packages might fail because our :ref:`PyPi Server` is not available publicly. In this case, you can often overwrite the ``PYPI_INDEX`` like this:

    .. code-block:: bash

        make develop PYPI_INDEX=https://pypi-public.confirm.ch

Development targets
~~~~~~~~~~~~~~~~~~~

+-------------+--------------------------------------------------------------------------------------------------------------------------+
|    Target   |                                                          Usage                                                           |
+=============+==========================================================================================================================+
| ``isort``   | Fix the Python imports via :ref:`isort`                                                                                  |
+-------------+--------------------------------------------------------------------------------------------------------------------------+
| ``server``  | Run the development server, e.g. `Django runserver <https://docs.djangoproject.com/en/3.1/ref/django-admin/#runserver>`_ |
+-------------+--------------------------------------------------------------------------------------------------------------------------+
| ``migrate`` | Run the database migrations, e.g. `Django migrations <https://docs.djangoproject.com/en/3.1/topics/migrations/>`_        |
+-------------+--------------------------------------------------------------------------------------------------------------------------+

Test targets
~~~~~~~~~~~~

Common test targets:

+-------------------+---------------------------------------------------------------------------------------------------------+
|       Target      |                                                  Usage                                                  |
+===================+=========================================================================================================+
| ``test``          | Run all tests for the project or package                                                                |
+-------------------+---------------------------------------------------------------------------------------------------------+
| ``test-commits``  | Validate the commits with the help of :ref:`git-tools' Validate Commits <Validate Commits>`             |
+-------------------+---------------------------------------------------------------------------------------------------------+
| ``test-unittest`` | Run the unit tests, e.g. `Python unittest <https://docs.python.org/3/library/unittest.html>`_           |
+-------------------+---------------------------------------------------------------------------------------------------------+
| ``test-packages`` | Run vulnerability checks on 3rd-party packages, e.g. `pip-audit <https://pypi.org/project/pip-audit/>`_ |
+-------------------+---------------------------------------------------------------------------------------------------------+

Python test targets:

+----------------------+---------------------------------------------------+
|        Target        |                       Usage                       |
+======================+===================================================+
| ``test-isort``       | Run the :ref:`isort` linter                       |
+----------------------+---------------------------------------------------+
| ``test-pycodestyle`` | Run the :ref:`pycodestyle` linter                 |
+----------------------+---------------------------------------------------+
| ``test-pylint``      | Run the :ref:`Pylint` linter                      |
+----------------------+---------------------------------------------------+
| ``test-django``      | Run the Django tests                              |
+----------------------+---------------------------------------------------+
| ``test-coverage``    | Show the coverage report, e.g. :ref:`Coverage.py` |
+----------------------+---------------------------------------------------+

Static files test targets:

+----------------------+-------------------------------------------------------------+
|        Target        |                            Usage                            |
+======================+=============================================================+
| ``test-eslint``      | Run the :ref:`ESLint` linter                                |
+----------------------+-------------------------------------------------------------+
| ``test-stylelint``   | Run the :ref:`stylelint` linter                             |
+----------------------+-------------------------------------------------------------+


:ref:`Visual regression test <Visual regression tests>` targets:

+----------------------+-------------------------------------------------------------+
|        Target        |                            Usage                            |
+======================+=============================================================+
| ``test-vrt``         | Run the visual regression tests                             |
+----------------------+-------------------------------------------------------------+
| ``vrt-approve``      | Approve the visual regression tests                         |
+----------------------+-------------------------------------------------------------+
| ``vrt-report``       | Open the visual regresion test report                       |
+----------------------+-------------------------------------------------------------+
| ``vrt-remote``       | Run the remote server for the visual regression test report |
+----------------------+-------------------------------------------------------------+

Build targets
~~~~~~~~~~~~~

+-----------+-----------------------------------------------------------------------------------------------+
|   Target  |                                             Usage                                             |
+===========+===============================================================================================+
| ``build`` | Build the project or package                                                                  |
+-----------+-----------------------------------------------------------------------------------------------+
| ``sdist`` | Build the `Python source distribution <https://docs.python.org/3/distutils/sourcedist.html>`_ |
+-----------+-----------------------------------------------------------------------------------------------+
| ``wheel`` | Build the `Python wheel <https://wheel.readthedocs.io/en/stable/>`_ binary package            |
+-----------+-----------------------------------------------------------------------------------------------+

.. _documentation-targets:

Documentation targets
~~~~~~~~~~~~~~~~~~~~~

+-------------+---------------------------------------------------------------------+
|    Target   |                                Usage                                |
+=============+=====================================================================+
| ``docs``    | Build the :ref:`Documentation`                                      |
+-------------+---------------------------------------------------------------------+
| ``autdocs`` | Watch the source and live build the :ref:`Documentation` on changes |
+-------------+---------------------------------------------------------------------+