From f8a6c8a415aeb11f9d5ea75b7a166952c54f1254 Mon Sep 17 00:00:00 2001 From: kaiyou Date: Sun, 5 Nov 2017 00:24:18 +0100 Subject: [PATCH] Add contributors documentations --- docs/contributors/database.rst | 69 ++++++++++++++++++++++++++++ docs/contributors/environment.rst | 39 ++++++++++++++++ docs/contributors/guide.rst | 73 ++++++++++++++++++++++++++++++ docs/contributors/localization.rst | 14 ++++++ docs/contributors/memo.rst | 33 ++++++++++++++ 5 files changed, 228 insertions(+) create mode 100644 docs/contributors/database.rst create mode 100644 docs/contributors/environment.rst create mode 100644 docs/contributors/guide.rst create mode 100644 docs/contributors/localization.rst create mode 100644 docs/contributors/memo.rst diff --git a/docs/contributors/database.rst b/docs/contributors/database.rst new file mode 100644 index 00000000..ca97f604 --- /dev/null +++ b/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. diff --git a/docs/contributors/environment.rst b/docs/contributors/environment.rst new file mode 100644 index 00000000..776ab64c --- /dev/null +++ b/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 diff --git a/docs/contributors/guide.rst b/docs/contributors/guide.rst new file mode 100644 index 00000000..fb5c7320 --- /dev/null +++ b/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). diff --git a/docs/contributors/localization.rst b/docs/contributors/localization.rst new file mode 100644 index 00000000..19af5574 --- /dev/null +++ b/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. diff --git a/docs/contributors/memo.rst b/docs/contributors/memo.rst new file mode 100644 index 00000000..e42dfeef --- /dev/null +++ b/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.