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
  1. 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