[documentation] Add contribution guidelines

This document explains how things are done when developing
for beat.editor.

doc/contribute.rst

+.. vim: set fileencoding=utf-8 :
+
+.. Copyright (c) 2019 Idiap Research Institute, http://www.idiap.ch/          ..
+.. Contact: beat.support@idiap.ch                                             ..
+..                                                                            ..
+.. This file is part of the beat.editor module of the BEAT platform.             ..
+..                                                                            ..
+.. Commercial License Usage                                                   ..
+.. Licensees holding valid commercial BEAT licenses may use this file in      ..
+.. accordance with the terms contained in a written agreement between you     ..
+.. and Idiap. For further information contact tto@idiap.ch                    ..
+..                                                                            ..
+.. Alternatively, this file may be used under the terms of the GNU Affero     ..
+.. Public License version 3 as published by the Free Software and appearing   ..
+.. in the file LICENSE.AGPL included in the packaging of this file.           ..
+.. The BEAT platform is distributed in the hope that it will be useful, but   ..
+.. WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY ..
+.. or FITNESS FOR A PARTICULAR PURPOSE.                                       ..
+..                                                                            ..
+.. You should have received a copy of the GNU Affero Public License along     ..
+.. with the BEAT platform. If not, see http://www.gnu.org/licenses/.          ..
+
+
+.. _beat-editor-contribute:
+
+===========================
+ Contribute to beat.editor
+===========================
+
+Development environment setup
+=============================
+
+Follow the same procedure as other beat package to setup a conda environment
+ready for development.
+
+#. Setup conda environment: ::
+
+   $ /path/to/bob.admin/conda/conda-bootstrap.py --overwrite --python=3.6 beat_editor_env
+
+#. Setup development environment: ::
+
+   $ buildout -c development.cfg
+
+#. Install the ``pre-commit`` package: ::
+
+   $ conda install pre-commit
+
+#. Setup ``pre-commit`` package: ::
+
+   $ pre-commit install
+
+#. You can run the pre-commit hooks at any time by calling: ::
+
+    $ pre-commit run --all-files
+
+
+beat.editor needs the following dependencies for its pre-commit hooks:
+
+    - black
+    - flake8
+    - bandit
+
+
+| black is currently available through Idiap's conda channel.
+| flake8 is available through conda's defaults channel.
+| bandit is not yet available on either so it must be installed using pip:
+
+::
+
+    $ pip install bandit
+
+If you would like to install them all using pip you can call: ::
+
+    $ pip install -r pre-commit-dependencies.txt
+
+
+Coding guidelines
+=================
+
+Coding style
+------------
+
+PEP8 rules should be followed when writing code for this module.
+
+In order to avoid having to nitpick about code style. black for python as well
+as flake8 will be used to ensure that formatting is enforced and doesn't let
+the developer wondering if he did it the right way.
+
+Pre-commit hooks will be run to ensure that.
+
+While developing, the hooks can be manually called: ::
+
+    $ pre-commit run --all-files
+
+This command will run the hooks on the whole repository. However more fine
+grained control can be applied.
+
+Commit guidelines
+=================
+
+Commit content
+--------------
+
+Commits should be atomic. What atomic means is that one commit should target
+one specific change.
+
+For example:
+
+#. Introduce new API with corresponding tests
+#. Implement use of new API in module1 with corresponding tests
+#. Implement use of new API in module2 with corresponding tests
+
+The same goes for fixes in, for example, the documentation. If the change is not
+related to code changes committed at the same time, then it should be a separate
+commit. This will avoid confusion and also allow for easier refactoring if
+needed.
+
+Commit message format
+---------------------
+
+The commit message format is the following:
+
+One summary line with the concerned module in brackets
+One blank line
+Longer multi-line description of what change and why it was changed.
+One blank line
+Meta information like bug fixed by the commit
+
+Example: ::
+
+    [widgets] Automatically update json preview
+
+    The preview content was only loaded at the same time as the file parsed.
+    Now changes to the file are automatically detected and the preview
+    refreshed.
+
+    Fixes #10
+
+
+If the change is trivial like fixing a typo in a variable name, the long
+description may be omitted.
+
+Commit message must be meaningful.
+
+For example: ::
+
+    [dependencies] Updated version
+
+is not acceptable as it doesn't provide any useful information beside "something
+has been update". This means that any developer going through the
+history log will have to open that specific commit to see exactly what changed
+and may only guess why it has changed.
+
+On the other hand: ::
+
+    [dependencies] Updated minimal foo version to X.Y.Z
+
+    Needed because of bug XXXXX
+
+is concise and makes it clear what happened and why.
+
+
+Branching guidelines
+====================
+
+Branching must be used for new features as well as bug fixes. Unless an
+exceptional circumstance occurs, one branch should implement one feature or
+one bug fix. If bug fixes or features depend on one of these branch, then a
+new branch should be created from there and then rebased as soon as the base
+branch was merged into master.
+
+Before merging occurs, each branch should be rebased on the latest master.
+
+As for the naming, branches should have meaningful names also.
+
+For example: ::
+
+   issue_20_fix_wrong_index
+   implement_dataformat_editor
+
+A branch doesn't need to be one commit, it can be but it can also span as many
+commits as needed in order to implement a feature or bug fix.
+
+Note that it may also happen that one branch contains fixes for several issues
+as they might be related.
+
+
+Merge message
+-------------
+
+Merge messages should again be meaningful and concise about the what and the
+why.