Add contributors documentations

docs/contributors/database.rst

@@ -0,0 +1,69 @@
+Altering the database
+=====================
+
+Alter the model code
+--------------------
+
+First alter the model code. Simply edit ``models.py`` and modify all required model classes.
+Make sure that your changes reflect on related classes as the migration should be consistent from one structure to another.
+
+Do not commit your changes at that stage.
+
+Generate the migration script
+-----------------------------
+
+After you modify the database models, you need to generate a new schema
+migration script:
+
+.. code-block:: bash
+
+  python manage.py db migrate
+
+This will generate a new script in ``migrations/versions`` that you must review
+before adding it for commit.
+
+Because we use SQLite, make sure that you use batch operation for column changes and deletion. For instance:
+
+.. code-block:: python
+
+  def downgrade():
+      with op.batch_alter_table('fetch') as batch:
+          batch.drop_column('last_check')
+          batch.drop_column('error')
+
+or
+
+.. code-block:: python
+
+  def upgrade():
+      # spam_threshold is a X/15 based value, we're converting it to percent.
+      for user in User.query.all():
+           user.spam_threshold = int(100. * float(user.spam_threshold or 0.) / 15.)
+      db.session.commit()
+
+      # set default to 80%
+      with op.batch_alter_table('user') as batch:
+          batch.alter_column('spam_threshold', default=80.)
+
+Remove unneeded Alembic comments and add a proper description to your migration script.
+
+Upgrade your local database
+---------------------------
+
+At that point, to start working on the changed database structure, you will need to upgrade your local database. Make a backup of your database, then:
+
+.. code-block:: bash
+
+  python manage.py db upgrade
+
+If any error arises, restore the backup, fix the migration script and try again.
+
+Actually work on your feature or fix
+------------------------------------
+
+If your changes to the database are related to a view or template, you may not work on these to reflect the changes and access the proper columns/tables.
+
+Commit your work
+----------------
+
+You may finally commit your work as a whole: database changes and view/template changes. Do not forget to add the migration script.

docs/contributors/environment.rst

@@ -0,0 +1,39 @@
+Development environment
+=======================
+
+Docker containers
+-----------------
+
+The development environment is quite similar to the production one. You should always use
+the ``testing`` version when developping. Simply uncomment the ``build`` directive on
+containers that you are working on and run:
+
+.. code-block:: bash
+
+  docker-compose build
+
+whenever you want to re-build them.
+
+Web administration
+------------------
+
+The administration Web interface requires a proper dev environment that can easily be setup using ``virtualenv`` (make sure you are using Python 3) :
+
+.. code-block:: bash
+
+  cd admin
+  virtualenv .
+  source bin/activate
+  pip install -r requirements.txt
+
+You can then export the path to the development database (use four slashes for absolute path):
+
+.. code-block:: bash
+
+  export SQLALCHEMY_DATABASE_URI=sqlite:///path/to/dev.db
+
+And finally run the server with debug enabled:
+
+.. code-block:: bash
+
+  python manage.py runserver

docs/contributors/guide.rst

@@ -0,0 +1,73 @@
+Development guidelines
+======================
+
+Philosophy
+----------
+
+The mailserver is designed as a whole, some images are therefore not best
+suited for reuse outside this project. All images should however follow
+Docker best practices and be as generic as possible :
+
+ - even if not suited for reuse, they should be simple enough to
+   fit as base images for other projects,
+ - interesting settings should be available as environment variables
+ - base images should be well-trusted (officiel Alpine or Debian for instance).
+
+Git workflow
+------------
+
+Forking vs. committing
+``````````````````````
+
+Linus' way of things sounds fine for now: if you find yourself implementing a
+new feature, either send me an email with a bunch of commits or use Github
+pull request feature. Maybe if the user base grows too much as well as the need
+for trust in a specific branch of the project, we can switch to a shared
+repository and add a couple of trusted committers.
+
+Commits
+``````
+
+This is a community project, thus commits should be readable enough for any of
+the contributors to guess the content by simply reading the comment or find a
+proper commit when one knows what he is looking for.
+
+Usual standards remain: write english comments, single line short comments and
+additional multiline if required (keep in mind that the most important piece
+of information should fit in the first line).
+
+Branches
+````````
+
+You are of course free of naming you branches to your taste or even using
+master directly if you find this appropriate. Still, keep in mind that:
+
+- a git email or a pull request should address a single feature a bug,
+  so keep your branches as tidy as possible;
+- this is a small project with a limited number of forks and active threads
+  on Github, so one might want to look at your fork and find the branch you
+  are using to implement a specific feature; to avoid any hassle, we suggest
+  that you use branch names prefixed with ``feat-`` or ``fix-`` and followed
+  either by the name of the Github issue or a short and meaningful name.
+
+Workflow
+````````
+
+All commits will be merged to the main ``master`` branch for testing. New
+images are built by Docker Hub with the ``testing`` tag for each new commit on
+the ``master`` branch.
+
+After some brief testing, urgent fixes will be cherry-picked to the current stable
+branch and new stable builds will be released.
+
+At the end of every milestone, a new stable branch will be created from ``master``
+or any previous commit that matches the completion of the milestone.
+
+Forked projects
+---------------
+
+If you find yourself forking the project for a specific independant purpose
+(commercial use, different phylosophy or incompatible point of view), we would
+be glad if you let us know so that we can list interesting known forks and
+their specific features (and backport some of them if your implementation
+is free as well).

docs/contributors/localization.rst

@@ -0,0 +1,14 @@
+I18N and L10N
+=============
+
+Using POEditor.com
+------------------
+
+We are using integrations with POEditor.com for translating Mailu. If you would like to contribute to the localization process, feel free to ask us to add a language then you can contribute to translations.
+
+The project : https://poeditor.com/join/project/VszspPuEpn
+
+Using Poedit
+------------
+
+If you prefer to work locally, Poedit is one of the best tools available out there. Feel free to commit on your own fork and pull request your translations.

docs/contributors/memo.rst

@@ -0,0 +1,33 @@
+Before requesting a pull
+========================
+
+Update translations
+-------------------
+
+Mailu uses Babel for internationalization and localization. Before any
+of your work is merged, you must make sure that your strings are internationalized
+using Babel.
+
+If you used ``_``, ``{% trans %}`` and other Babel syntaxes in your code, run the
+following command to update the POT file:
+
+.. code-block:: bash
+
+  pybabel extract -F babel.cfg -k lazy_gettext -o messages.pot mailu
+
+The, update the translations:
+
+.. code-block:: bash
+
+  pybabel update -i messages.pot -d mailu/translations
+
+Please resolve fuzzy strings to the best of your knowledge.
+
+Update information files
+------------------------
+
+If you added a feature or fixed a bug or committed anything that is worth mentionning
+for the next upgrade, add it in the ``CHANGELOG.md`` file.
+
+Also, if you would like to be mentionned by name or add a comment in ``AUTHORS.md``,
+feel free to do so.