Mailu/docs/contributors/guidelines.rst

Project guidelines
==================

Why these guidelines
--------------------

This page is written as an evolving memo of the main development guidelines
that we follow or should follow as contributors. Some are basic development
constraints, some are architectural opinions.

If you contribute to this project, please read through them all and read the
architectural documentation. Reviewers will check that your contributions
match these guidelines among other things.

If you feel one of the guidelines is wrong or incomplete, please come and
discuss on our messaging channel, then open a pull request including the
change you would like to make and the reasons why in the description, we can
then formally discuss it and review it following our usual review process.

General
-------

What features should be included
````````````````````````````````

Mailu is a mail server. That said, mail works in an ecosystem and we should set
clear boundaries on what Mailu is and what it is not. Beyond mail, we include
features that mail is dependent on in some way, not the other way aroud.

For instance, we include contact management and a dav service for synchronizing
contacts, because sending mail is made easier with manageable contacts. We do
not include a calendar management app or file sharing app, because mail is not
dependent on them.

Examples of features we will not include in Mailu are: calendars, documents and
file sharing, full-sized groupware, instant messaging, password management. If
you want and success in connecting those to Mailu and want to share, please
write some useful documentation for others to do the same.

What behavior is tolerated
``````````````````````````

Be respectful of others and others contributions. If you find a whole part of
Maiu is terribly written or badly designed, please open an issue to discuss it
calmly or come and have a chat on our channel.

Any PR that just rewrites a huge part of the code by making mostly cosmetic or
opinionated changes without prior discussion will be received with a polite
"no".

Architecture
------------

What setups should be supported
```````````````````````````````

Mailu supports out-of-the-box Docker Compose, Docker Swarm and Kubernetes
environments. In those environments, it consists of many containers and
supports hosting some of those containers in a separate environment.

It supports hosting the data outside of the environment, in as many types of
database servers as can be documented.

It supports spreading and scaling the containers across hosts, except for
those that share volumes. The intention is to stop sharing volumes between
containers.

What is a Mailu container
`````````````````````````

A Mailu container should provide one service and run one type of process only.
A new Webmail should be in a separate container, a new antivirus or a new
antispam should be in a separate container.

A container is developped as a singled directory under the proper category in
the main repository, the only exception being service containers that should
only use official Docker images. Categories are:

- core, for mandatory components
- optional, for optional components
- webmail, for webmails

A container image name must explicitely state the technology being used.
Container versions are synchronized and all containers are always built at
once. The service name associated in the Compose file or Kubernetes configuration
should match the container image name.

How configuration should be managed
```````````````````````````````````

Anything that is static should be managed using environment variables.
Configuration files should be compiled at runtime by the container `start.py`
script and all conditional syntax should be handled using Jinja logic.

The `socrate` Python package should include relevant functions for container
lifecycle management.

Anything that is not static, i.e. able to change at runtime, either due to
configuration in the admin ui or user behavior, should take advantage of the
admin API. The `podop` package binds mail specific sofware (Postfix and Dovecot
at the moment) to the admin API, other containers should use specific API calls.

What traffic should go through the nginx container
``````````````````````````````````````````````````

All of it. All traffic, including HTTP(S), IMAP, SMTP, POP3, should go through
the front container.

More generally, the front container is responsible for routing that traffic based
on the incoming port or the HTTP browsing logic. It handles protocol rewriting
for security, authentication, rejects based on identity or IP address.

How browsing should be managed
``````````````````````````````

The nginx container is responsible for routing all Web traffic. Web traffic should
go directly from the nginx container to the target container.

All traffic to a container should be accessed at ``/<container_name>`` for a given
container. If multiple types of traffic are routed for a specific container, they
should be accessed at ``/<container_name>/<traffic_type_a>`` and
``/<container_name>/<traffic_type_b>``, for instance ``/admin/ui`` or
``/admin/api``.

Traffic directed to ``/`` should be routed to an endpoint on the admin container
responsible for dynamically redirecting it. That last redirect must use a
302.

Any traffic to a non existing endpoint must return a 404.


How authentication should work
``````````````````````````````

Authentication should be managed by the nginx container, based on the admin
container API. The only exception is authentication to the admin container
itself, that is handled directly.

Authentication API in the admin container should contain the logic for
account management (allowed features, etc.) and rate limiting.

Configuration
-------------

Where should configuration files be stored
``````````````````````````````````````````

Configuration files should ideally be stored in the most standard place for the
tool being configured. For instance, if the tool usually accepts configuration
files in ``/etc``, then configuration should be written there.

Should we use default configuration
```````````````````````````````````

Some tools ship with default configuration, that handles the standard behavior.
Using this configuration is prone to later changes and unexpected side effects.
We should always provide all required configuration, including the base files,
and not rely on default configuration files froms the distribution.

For that reason, in case the tool looks for specific files and include them
automatically, we should overwrite them or delete them.

How should configuration be overridden
``````````````````````````````````````

Some containers support configuration override. For this feature, we should
ideally look for conditional configuration inclusion in the configuration syntax
and use it. If the tool supports multiple methods of overrides, we should use
the one that supports overriding the more configuration.

In case the tool does not support conditional inclusion, we can add the
override logic in the `start.py` script.

How much should configuration be documented
```````````````````````````````````````````

We should not keep default documentation included by the distribution when
providing configuration files.
We should organize configuration files in section relevant to the type of things
we configure.
We should add comments, and point to Github issues or public documentation when
required, in order to make our choices explicit.

Coding
------

Coding standards
````````````````

All Python code should comply with PEP-8. We should review our code using
pylint.

We should comply with architectural recommendations from the Flask
documentation.

Models and database
```````````````````

All model classes should only use generic types that are compatible with most
supported database backends.

No database specific configuration should be included in the models, no table
name should be forced and no schema specifics should be configured. These
should be handled by the migration scripts and only used when absolutely
necessary.

Updating the dependencies
`````````````````````````

Every major change to the admin Python code should be preceded by an upgrade
of the dependencies. The dependency upgrade should be tested then provided
as a separate PR before the actual changes.