Contribution guidelines
=====================================

<p align="center">
    Minimalist And Customisable Optimisation Package
</p>


# Welcome !

Thank you for taking the time to read this guide for the package's contribution. I'm glad to know that you may bring a lot to the **Macop** package. This document will show you the good development practices used in the project and how you can easily participate in its evolution!

# Table of contents

1. [Naming conventions](#naming-conventions)

    1.1. [Git naming conventions](#git-naming-conventions)

    1.2. [Package modules conventions](#package-modules-conventions)

2. [Coding conventions](#coding-conventions)

    2.1. [Python conventions](#python-conventions)

    2.3. [Code documentation](#code-documentation)

    2.2. [Test implementation](#test-implementation)

3. [Submission process](#submission-process)

    3.1. [Build package](#build-package)

    3.2. [Pull request](#pull-request)

4. [Request an enhancement or report a bug](#request-an-enhancement-or-report-a-bug)

# Naming conventions

## Git naming conventions

This project uses the naming conventions of the git branches set up by the [git-flow](https://danielkummer.github.io/git-flow-cheatsheet/) interface. To make your contribution as easy as possible to inject into the project, you will need to name your git branch as follows:

```bash
git branch feature/YourFeatureBranchName
```

Using git-flow interface:

```bash
git flow feature start YourFeatureBranchName
```

## Package modules conventions

As you perhaps already saw, package contains multiples modules and submodules. It's really import to be well organized package and let it intuitive to access as possible to features.

For the moment there are no precise conventions on the naming of new modules or sub-modules, it must just in a first step respect the hierarchy already in place and avoid any redundancies.

In order to facilitate the integration of new modules, do not hesitate to let me know the name it could have beforehand.

# Coding conventions

## Python conventions

This project follows the [coding conventions](http://google.github.io/styleguide/pyguide.html) implemented by Google. To help you to format **\*.py** files, it is possible to use the [yapf](https://github.com/google/yapf/) package developed by Google.

Note that the **yapf** package is used during build process of **macop** package to format the whole code following these conventions.

## Code documentation

In order to allow quick access to the code, the project follows the documentation conventions (docstring) proposed by Google. Here an example:

```python
''' Binary integer solution class

    - store solution as a binary array (example: [0, 1, 0, 1, 1])
    - associated size is the size of the array
    - mainly use for selecting or not an element in a list of valuable objects

    Attributes:
       data: {ndarray} --  array of binary values
       size: {int} -- size of binary array values
       score: {float} -- fitness score value
'''
```

You can generate documentation and display updates using these following commands:

```
bash build.sh
firefox docs/index.html
```

Do not forget to generate new documentation output before doing a pull request.

## Test implementation

This project use the [doctest](https://docs.python.org/3/library/doctest.html) package which enables to write tests into documentation as shown in example below:

# TODO : add custom example
```python
""" Initialise binary solution using specific data

    Args:
        data: {ndarray} --  array of binary values
        size: {int} -- size of binary array values

    Example:

    >>> from macop.solutions.discrete import BinarySolution
    >>> # build of a solution using specific data and size
    >>> data = [0, 1, 0, 1, 1]
    >>> solution = BinarySolution(data, len(data))
    >>> # check data content
    >>> sum(solution._data) == 3
    True
    >>> # clone solution
    >>> solution_copy = solution.clone()
    >>> all(solution_copy._data == solution._data)
"""
```

Moreover, tests written are displayed into generated documentation and let examples of how to use the developed function.

# Submission process

## Build pakcage

One thing to do before submit your feature is to build the package:

```bash
python setup.py build
```

This command do a lot of thing for you:
  - Runs the tests from documentation and raise errors if there are.
  - Formats all **\*.py** inside *macop* folder using **yapf**.

Do not forget to build documentation as explained in section [2.3](#code-documentation).

Or directly use bash script which runs all you need:

```bash
bash build.sh
```

## Pull request

Once you have built the package following previous instructions. You can make a pull request using GitHub. A [documentation](https://help.github.com/articles/about-pull-requests/) about pull requests is available.

# Request an enhancement or report a bug

To enhance the package, do not hesitate to report bug or missing feature. To do that, just submit an issue using at one of this labels:

- **feature** or **idea**: for new an enhancement to develop
- **bug:** for a detected bug

You can also add your own labels too or add priority label:

- prio:**low**
- prio:**normal**
- prio:**high**

Main common required issue header:

```
Package version: X.X.X
Issue label: XXXXX
Priority: prio:**level**
Targeted modules: `macop.algorithms`, `macop.policies`
Operating System: Manjaro Linux

Description: XXXXX
```

Whatever the problem reported, I will thank you for your contribution to this project. So do not hesitate.