From 267139fb89e918ab0dff19e7dc20d1f7e9a8f3dc Mon Sep 17 00:00:00 2001 From: Samuel Gaist <samuel.gaist@idiap.ch> Date: Thu, 3 Jan 2019 11:26:36 +0100 Subject: [PATCH] [documentation] Add contribution guidelines This document explains how things are done when developing for beat.editor. --- doc/contribute.rst | 192 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 doc/contribute.rst diff --git a/doc/contribute.rst b/doc/contribute.rst new file mode 100644 index 00000000..1ae9cd26 --- /dev/null +++ b/doc/contribute.rst @@ -0,0 +1,192 @@ +.. 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. -- GitLab