###########################
Contributing to the project
###########################

This document provides guidelines for people who want to contribute to the
wardrobe project.


**************
Create tickets
**************

Please use the `bugtracker`_ **before** starting some work:

* check if the bug or feature request has already been filed. It may have been
  answered too!
* else create a new ticket.
* if you plan to contribute, tell us, so that we are given an opportunity to
  give feedback as soon as possible.
* Then, in your commit messages, reference the ticket with some
  ``refs #TICKET-ID`` syntax.


***************
Fork and branch
***************

* Work in forks and branches.
* Prefix your branch with the ticket ID corresponding to the issue. As an
  example, if you are working on ticket #23 which is about contribute
  documentation, name your branch like ``23-contribute-doc``.


*******************************
Setup a development environment
*******************************

System requirements:

* `Python`_ version 2.6 or 2.7, available as ``python`` command.
  
  .. note::

     You may use `Virtualenv`_ to make sure the active ``python`` is the right
     one.

* make and wget to use the provided :file:`Makefile`.

Execute:

.. code-block:: sh

  git clone git@github.com/benoitbryon/wardrobe.git
  cd wardrobe/
  make develop

If you cannot execute the Makefile, read it and adapt the few commands it
contains to your needs.


************
The Makefile
************

A :file:`Makefile` is provided to ease development. Use it to:

* setup the development environment: ``make develop``
* update it, as an example, after a pull: ``make update``
* run tests: ``make test``
* run benchmarks: ``make benchmark``
* build documentation: ``make documentation readme``

The :file:`Makefile` is intended to be a live reference for the development
environment.


*************
Documentation
*************

Follow `style guide for Sphinx-based documentations`_ when editing the
documentation.


**************
Test and build
**************

Tests and builds will automatically be triggered before commit:

* tests include the build of documentation and README as HTML.
* a `Git pre-commit hook`_ is installed during the development environment
  setup.

If you want to run them manually, use `the Makefile`_.


**********
References
**********

.. target-notes::

.. _`bugtracker`: 
   https://github.com/benoitbryon/wardrobe/issues
.. _`Python`: http://python.org
.. _`Virtualenv`: http://virtualenv.org
.. _`style guide for Sphinx-based documentations`:
   http://documentation-style-guide-sphinx.readthedocs.org/
.. _`Git pre-commit hook`: http://git-scm.com/book/en/Customizing-Git-Git-Hooks