development.rst

Development

This is the documentation for developers of the Mentat library itself, or developers of components and modules usable by or pluggable into the Mentat system.

Key information

• Project Mentat: official website
• Project Warden: official website
• IDEA: official website
• Project issue tracking system (Redmine)
• Primary source code repository (Git)
• Automated build system (Alchemist)

Getting the code

We are using the Git SCM system to manage our codebase. Please follow instructions in section :ref:`section-installation-git` to install the project into your desired location. By following these instructions a Python virtual environment will be initialized for you, all requirements (including those required only for development) will be installed and finally the project itself will be installed locally in editable mode.

General guidelines

• Let PEP 20 be the guide for your mind.
• Let PEP 8 be the guide for your hand.
• Let you and PEP 257 and PEP 287 be the guide for others.
• Use Sphinx-doc format to document the code.
• Pull and merge often.
• Use devel branch for small updates and bugfixes.
• For bigger features fork devel, merge after accepting, delete branch.
• Use release branch only for code that is ready to be released into production.
• Use master branch only for production level and stable code.
• master and release branches must not break unittests, lint or build in general. devel branch should not.
• Unless you have been explicitly allowed to, do not use master and release branches.
• New feature should be accompanied with unit tests.
• Do not introduce new dependencies into core library. Dependent code should go into its own submodule, so dependency can be runtime and enforced by system administrator if necessary, but not by library.
• Reuse existing (even soft) dependencies. There is no need to use three competing IP address libraries. However, do not prevent application developer to use different one in his app, should he need to.

Development essentials

There is a project master Makefile in the root of the project repository which can perform various essential or useful development tasks. You can get the full list of all available make commands/targets by executing one of the following commands:

$ make
$ make help

Of course you need to have make utility installed on your system, on Debian-based system you can use following command:

$ aptitude install make

It is recommended to always install the project into Python virtual environment. If you have followed the installation instructions in section :ref:`section-installation-git` this virtual environment was set up for you in ./venv subdirectory. Before any development work do not forget to activate the environment with:

# Activate virtual environment before any development work:
$ . venv/bin/activate

# Deactivate virtual environment when it is not needed anymore with:
(venv) $ deactivate