lakesuperior_legacy/docs/contributing.rst

Contributing to Lakesuperior
============================

Lakesuperior has been so far a single person’s off-hours project (with much
valuable input from several sides). In order to turn into anything close
to a Beta release and eventually to a production-ready implementation, it
needs some community love.

Contributions are welcome in all forms, including ideas, issue reports,
or even just spinning up the software and providing some feedback.
Lakesuperior is meant to live as a community project.

.. _dev_setup:

Development Setup
-----------------

To set up the software for developing code, documentation, or tests, start in
an empty project folder::

    python3 -m venv venv
    source venv/bin/activate
    git clone --recurse-submodules https://github.com/scossu/lakesuperior.git src
    cd src
    pip install -e .

This will allow to alter the code without having to re-run ``pip install``
after changes (unless one is changing the Cython modules; see below).

Modifying Cython Modules
------------------------

Cython files must be recompiled into C files and then into binary files every
time they are changed. To recompile Lakesuperior modules, run::

    python setup.py build_ext --inplace

For a faster compilation while testing, the environment variable ``CFLAGS``
can set to ``-O0`` to turn off compiler optimization. The runtime code may run
slower so this is not recommended for performance benchmarking.

Refer to the `Cython documentation
<http://docs.cython.org/en/latest/src/userguide/source_files_and_compilation.html>`__
for a detailed description of the Cython compilation process.

Contribution Guidelines
-----------------------

You can contribute by (from least to most involved):

- Installing the repository and reporting any issues
- Testing on other platforms (OS X, Windows, other Linux distros)
- Loading some real-world data set and sharing interesting results
- Amending incorrect documentation or adding missing one
- Adding test coverage (**HOT**)
- Browsing the list of open issues and picking a ticket that you may find
  interesting and within your reach
- Suggesting new functionality or improvements and implementing them

Please open a ticket and discuss the issue you are raising before opening a PR.

Documentation is critical. If you implement new modules, classes or methods, or
modify them, please document them thoroughly and verify that the API docs are
displaying and linking correctly.

Likewise, please add mindful testing to new fatures or bug fixes.

Development is done on the ``master`` branch. If you have an addition to the
code that you have previously discussed by opening an issue, please fork the
repo, create a new branch for your topic and open a pull request against
master.

Last but not least, read carefully the `Code of Conduct
<https://github.com/scossu/lakesuperior/blob/master/code_of_conduct.md>`__.