Contributing to AIDApy

All contributions are welcome. For detailed information about the code style please read the following instructions. All the code must have a adequate number of tests that assures it’s credibility. Feel free to make pull requests.

Introduction

This guide defines the conventions for writing Python code for aidapy. The main ideas are:

  • ensuring a consistent code style

  • promote good practices for testing

  • maintaining a good level of readability and maintainability

  • to keep it simple

Python version

Prefer if possible Python>=3.6 since there are major dependencies that do not support other python versions. There is no reason motivating the use of Python 2 as AIDApy is not using dependencies or legacy code.

Coding style

Stick as much as possible to PEP8 for general guidelines in term of coding conventions and to PEP257 for typical docstring conventions. You can also have a look to Python anti-pattern.

Main guidelines from PEP8

PEP8 coding conventions are:

  • Use 4 spaces per indentation level.

  • Limit all lines to a maximum of 100 characters.

  • Separate top-level function and class definitions with two blank lines.

  • Imports should be grouped in the following order:

  • Standard library imports.

  • Related third party imports.

  • Local application/library specific imports.

  • A blank line between each group of imports.

Use Linters

Linters are tools for static code quality checker. For instance, you can use the following tools to test conformity with the common pythonic standards:

  • pylint is one of the oldest linters and tracks various problems such as good practice violation, coding standard violation, or programming issues. Pylint may be seen as slow, too verbose and complex to configure to get it working properly. You can run a complete static analysis with the following command:

pylint aidapy --rcfile=setup.cfg --ignore-patterns='file_to_ignore1.py','file_to_ignore2.py'

All these linters can be simply installed with pip. Further details on the functionnalities can be found here or there. Also, a lot of features can also be provided natively or by installing plugins with your IDE (PyCharm, Spyder, Eclipse, etc.).

Documentation

Please follow the numpy guidelines to comment your code. All the function and classes have to be commented.

Documentation of all the files must be done in-line using Sphinx. We strongly encourage you to setup a documentation using doctest.

Testing

The library pytest is used to launch tests in the code. All tests can be launched using:

coverage run -m pytest

This command gives coverage at the same time. The output consists in tests results and coverage report.

Regarding the location of the test files, add a directory where you will keep the unit tests for each individual modules of the package.

<AIDApy_root>/aidapy/<mymodule>/tests

Each test must be minimal and should ensure non-regression, and full functionality of the module. The files should be named:

  • test_<name>.py where <name> is any name you think representative of the test.

Integration tests will be kept in the following directory. Do not forget that integration tests are those that involve two or more sub-modules of the aidapy package.

<AIDApy_root>/tests

These tests are handled by the package integration team.

Using the git repository

You will always work in a branch different from master. The general rule is the following (source):

  • The production version of your code sits in a branch named master.

  • The development version of your code (ready to be tested and productionised) sits in a branch named develop.

  • When development on a new feature is started, a new branch is created off of the develop branch. This is a feature branch.

  • When development has completed, the feature branch is either merged back into the develop branch if the changes are to be taken into production, or left in their respective branch if they are not.

  • When the code in the develop branch is finally ready to be released into production, a new release branch is created.

  • When the release branch is approved for release, it is merged into the master branch and develop branch to capture any fixes that may have been done directly on the release branch.

When you are working on your feature branch, commit often, every time that an consistent modification is made. Please use meaningful commit messages: follow the standards presented in the guide How to write a git commit message.

Remember to always merge the latest version of the master branch to your branch before any commit. Please check that your code works and passes the standardization tool tests before requesting a merge to the master branch.

Once you are sure that your branch is in good conditions to share it with the developers and users, please make a merge request on gitlab.

Testing Standards

In order the merging request (of the feature branch to master branch ) to be authorized the feature branch must pass successfully from the Continuous Integration tools. To achieve this, the score of the pylint library must be over 8.0 / 10.0 and the test coverage above 80%.

For assessing the pylint score run the command:

pip install pylint
pylint aidapy --rcfile=setup.cfg

Finally for assessing the code test coverage of your branch run:

coverage run setup.py test