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/
- 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)
- Clone your repo locally (This is done once!)
git clone git@github.com:_username_/libNeuroML.git
- 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.
Push the branch online
git push origin fix-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