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.

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.

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

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.