How to contribute
=================

To contribute to libNeuroML you need a github account then you should
fork the repository at https://github.com/NeuralEnsemble/libNeuroML

Note: Fork is not a bad thing on a Github workflow. Fork basically
means you have your own repository which is connected with upstream 
(the main repository from which official releases will be made). You
can contribute back to upstream using `Pull Request`_

Setting up
----------

Have a quick view at the doc: http://help.github.com/fork-a-repo/

1. Fork the repo (done on github website). 
   Now you should have a libNeuroML under you username (mine for example sits 
   happily here: https://github.com/mattions/libNeuroML)

2. Clone your repo locally (This is done once!)

::

    git clone git@github.com:_username_/libNeuroML.git

3. Add upstream as remote branch which you follow

::

    cd libNeuroML
    git remote add upstream https://github.com/NeuralEnsemble/libNeuroML.git
    git fetch upstream

You can check which branch are you following doing:

::

    git branch -a

you should have something like:

::

    mattions@triton:libNeuroML(master*)$ git branch -a
    * master
      remotes/origin/HEAD -> origin/master
      remotes/origin/master
      remotes/upstream/master

This means you are currently on branch master and there are two remotes
branches ``origin/master`` which is your origin master (the branch where
you master gets pushed automatically and ``upstream/master`` which is
the upstream master (the NeuroEnsemble one).

Sync with upstream
------------------

Before starting to do some work, I’ll suggest to get the latest
development going on the upstream repo

::

    git fetch upstream
    git merge upstream/master

If there are no conflict, you are all set, if there are some you can
solve them with

::

    git mergetool

which will fire up your favourite merger to do a 3-ways merge.

3-ways means you will have your *local* file on your left, the *remote*
file on your right, and the file in the middle is the conflicted one,
which you need to solve.

A nice 3-ways merger makes this process very easy, and merging could be
fun. To see what you have currently installed just do ``git mergetool``

This is my response

::

    mattions@triton:libNeuroML(master*)$ git mergetool
    merge tool candidates: meld opendiff kdiff3 tkdiff xxdiff tortoisemerge gvimdiff diffuse ecmerge p4merge araxis bc3 emerge vimdiff
    No files need merging

[Meld] (http://meldmerge.org/) is the first of the list and would be
automatically picked up by ``git mergetool``. Chose your favourite.

Well done, now you are all set to do some cool work!

Working locally on a dedicated branch
-------------------------------------

Now you can work on your repo. The best way to do it is to create a
branch with a descriptive name which indicate what are you working on.

For example, just for the sake of this guide, I’m going to close `#2`_

::

    git checkout -b fix-2

Now, I’m working on a different branch from master which is fix-2 This
will come handy in a minute.

::

    hack hack hack
    git commit -am "some decent commit message here"

Now that I found how to fix this issue, I just want to push my branch
online and open a pull request.

1. Push the branch online

   ::

       git push origin fix-2

2. Open the pull request

Here I want to open a pull-request to integrate ``fix-2`` into
``upstream/master``

To do that I click Pull-Request and automatically a new Issue `#3`_ is
created where it is possible to comment.

If your code is not ready to be include, you can update the code on your
branch and automatically the Pull Request will sync to the latest
commit, so it is possible to change it after the Pull Request is
started. Don’t be scare to open one.

Release process
---------------
libNeuroML is part of the official NeuroML release cycle. As of
1/09/13 we are still ironing out the proecure. When a new libNueroML
release is ready the following needs to happen:
  - Update version number in setup.py
  - update version number in doc/conf.py
  - update release number in doc/conf.py (same as version number)
  - update changelog in README.md
  - merge development branch with master (This should happen via pull
    request - do not do the merge yourself even if you are an owner
    of the repository.
  - push latest release to PyPi

Miscellaneous
-------------

-  `Nice guide about git`_

-  `Quick reference for git`_

-  Remember to `tell git your name`_, so we know who contributes!

-  Always known in which branch you are using this `bash function`_

.. _Pull Request: http://help.github.com/send-pull-requests/
.. _#2: https://github.com/NeuralEnsemble/libNeuroML/issues/2
.. _#3: https://github.com/NeuralEnsemble/libNeuroML/issues/3
.. _Nice guide about git: http://rogerdudler.github.com/git-guide/
.. _tell git your name: http://help.github.com/set-your-user-name-email-and-github-token/
.. _bash function: https://gist.github.com/2051095
.. _Quick reference for git: http://gitref.org/