===========
Development
===========

This document aims to explain how the E-Shop 4.0 project is developed.
The ``eshop4`` repository contains a primary package structure for
the base modules required to install and run a "standard eshop".

Structure
=========

- ``docs``
   At the root level you'll find the ``docs`` directory, which contains
   technical documentation files, such as this one.

- ``eshop``
   The primary ``eshop`` Python package is contained in this folder.
   It contains the modules that can be installed as Django apps in a project.

- ``project``
   An example Django project containing a ``manage.py`` file to get it up
   and running instantly. This project is also used to run tests against.

- ``tests``
   Location for unit and integration tests. Test runner and setup is to be defined.

Coding Style
============

We try to follow coding standards that the Python community at large can agree on.
This mostly means PEP8 with a few additions and or modifications here and there.

Refer to the `Django coding guidelines`_ and use ``flake8`` as a tool to automatically
check for style guide conformance.

.. _Django coding guidelines: https://docs.djangoproject.com/en/2.0/internals/contributing/writing-code/coding-style/

HTML Style
----------

- Use double quotes for everything, if possible (including Django template tags).
- Try to limit line length to 120 characters.
- When breaking lines within tags, write attributes indented on a new line, and the closing bracket on a separate line.

JS Style
--------

- See .eslintrc

SCSS Style
----------

- See .stylelintrc

i18n
----

- Translation tags should be written in German, without any text transformation.
- Adverbs, adjectivs and verbs ("cancel") should begin with a lowercase letter.
- Full sentences ("Please click here to...") should begin with an uppercase letter.
- Use blocktrans tag in templates when having translation tags with params::

  {% blocktrans trimmed with n=7 %}We found {{ n }} items.{% endblocktrans %}

Translating messages
~~~~~~~~~~~~~~~~~~~~

To provide translations for strings and other texts provided in this
eshop repository, you may use the utility commands included::

   invoke makemessages

These commands will update all available translation catalogs with
changed or newly added translatable texts.
Located in ``eshop/locale``, these files are plaintext and can be edited in your favorite text
editor. You may also use tools like `PoEdit`_ that allow you to work faster.

.. _PoEdit: https://poedit.net/

Add a new language
~~~~~~~~~~~~~~~~~~

To add a new language to the provided translations, you must initially
create the catalog by issuing this command::

   cd eshop
   DJANGO_SETTINGS_MODULE= django-admin makemessages --locale <LANG>

Unsetting the ``DJANGO_SETTINGS_MODULE`` environment variable ensures
no import errors happen when trying to create messages.

Dependency management
=====================

Pipenv is used to manage project dependencies and ensure reproducible builds.
Ensure you have ``pipenv`` available on your system or `install it`_ using::

   pip install pipenv

.. _install it: https://docs.pipenv.org/install/#installing-pipenv

A single E-Shop Django project will use Pipenv to manage its dependencies. This repo
contains a Pipfile with a corresponding lock file to manage the example project's
requirements.

However, it is **not** suited to manage dependencies of the ``eshop`` package.
Dependencies for the core ``eshop`` package are managed by the requirements.txt and requirements-dev.txt files, respectively.

To add a new dependency to the core ``eshop`` package, append the requirements line to the corresponding ``requirements.txt`` file.

You may also add the dependency to the example_eshop project included
in this repository::

   pipenv install package_name

This will install the latest stable and published version of the package
and pin the exact revision number to ``Pipfile.lock``.
To install a package that is *only* needed for development (e.g. testing, linting),
use the ``--dev`` flag after the ``install`` argument::

   pipenv install --dev flake8

The requirements should be chosen so that any project can be run without the dev dependencies.

Database modifications
======================

Django ships with its own migration management tool. To use it, simply
modify the model fields with your desired changes and run::

   ENABLE_MODEL_T9N=False ./manage.py makemigrations

Please ensure the ``ENABLE_MODEL_T9N`` environment variable is set to ``False``, as it ensures no migration files will be created for
newly added translated fields. I18N Fields are managed separately
in each project by using ``sync_translation_fields``.

Testing
=======

The ``eshop`` package can be tested using ``pytest``. To run all tests, ensure you have installed the ``--dev``
dependencies with ``pipenv`` and run the command from the project's root directory::

    $ pytest

Several options are available. To speed up consecutive test runs, you might want to use the ``--reuse-db`` flag
which will use the previously created test database. This prevents running all migrations at the start of each
test run.

Writing tests
-------------

Several helper fixtures are available, provided by ``pytest-django``. Refer to `their documentation`_ to aid
in writing tests for Django specific functions.

.. _their documentation: https://pytest-django.readthedocs.io/en/latest/helpers.html