.. _contributing:

Contributing
============
This is a simple remainder on how to change/add things to the library.

First rule of thumb is to follow the obvious naming/structure conventions used in the repository.

Working on the C++ backend
--------------------------

If the developped feature requires to create a new file `include/higra/file-path/filename.hpp`:

    - create the file (add minimal licence and namespace information)
    - create the test file `test/cpp/file-path/test_filename.cpp` (add minimal licence information and boost test module initialization)
    - register test file in `test/cpp/file-path/CMakeLists.txt`

Working on the Python frontend
------------------------------

If the feature requires to create a new python file `higra/file-path/filename.py`:

    - create the file (add minimal license information)
    - register file in `higra/file-path/CMakeLists.txt`
    - add line `from .filename.py import *` in `higra/file-path/__init__.py`
    - add a new python test file `test/python/file-path/test_filename.py`
    - register test file in `test/python/file-path/CMakeLists.txt`

If the feature requires to create a new c++ pybind11 binding for the backend file `include/higra/file-path/filename.hpp`:

    - create the files `higra/file-path/py_filename.hpp` and `higra/file-path/py_filename.cpp`
    - declare prototype `void py_init_filename(pybind11::module &m);` in the hpp file and implement it in the cpp file.
    - register the cpp file in `higra/file-path/CMakeLists.txt`
    - add line `#include "py_filename.hpp"` to `higra/file-path/all.hpp`
    - add line `py_init_filename(m);` in `higra/py_module.cpp`
    - add a new python test file `test/python/file-path/test_filename.py`
    - register test file in `test/python/file-path/CMakeLists.txt`

If the feature requires to create a new top-level package `package-name`:

    - create the folder `higra/package-name/`
    - add files `__init__.py`, `CMakeLists.txt`, "all.hpp" in the new folder
    - in `higra/all.hpp` add `#include "package-name/all.hpp"`
    - in `higra/CMakeLists.txt` add `add_subdirectory(package-name)`
    - in `higra/__init__.py` add `from .package-name import *`
    - in `setup.py` add `'higra.package-name'` in package list

Pushing a new version
---------------------

.. important::

    Admin only

  - Change version number in `include/higra/config.hpp` and in `doc/requirements.txt`: `x.y.z`
  - push new version to master/origin
  - Add tag `x.y.z` to master
  - push tag to master/origin
  - (linux/mac/windows Pypi wheels generated automatically with `Travis Ci <https://travis-ci.com/>`_ and `Appveyor <https://www.appveyor.com/>`_)
  - regenerate docs when Pypi is up-to-date `readthedocs <https://readthedocs.org/projects/higra/>`)