Merge #1151
1151: Start writing the contribution guidelines r=mergify[bot] a=kaiyou ## What type of PR? Documentation ## What does this PR do? It provides a first suggested version of contribution guidelines for the project. These are very open do discussion. This was suggested in #1133. ## Prerequistes - [x] In case of feature or enhancement: documentation updated accordingly - [x] Unless it's docs or a minor change: add [changelog](https://mailu.io/master/contributors/guide.html#changelog) entry file. Co-authored-by: kaiyou <pierre@jaury.eu>master
bors[bot]
5 years ago
committed by
GitHub
commit
89413a8da9
@ -0,0 +1,212 @@
|
|||||||
|
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.
|
||||||
Loading…
Reference in New Issue