Contributing to NineML¶
Mailing list¶
Discussions about Python nineml
take place in the
NeuralEnsemble Google Group.
Setting up a development environment¶
Requirements¶
In addition to the requirements listed in Installation, you will need to install:
to run tests, and:
to build the documentation.
Code checkout¶
NineML development is based around GitHub. Once you have a GitHub account, you should fork the official NineML repository, and then clone your fork to your local machine:
$ git clone https://github.com/<username>/nineml-python.git nineml_dev
$ cd nineml_dev
To work on the development version:
$ git checkout master
To keep your NineML repository up-to-date with respect to the official repository, add it as a remote:
$ git remote add upstream https://github.com/INCF/nineml-python.git
and then you can pull in any upstream changes:
$ git pull upstream master
We suggest developing in a virtualenv, and installing nineml
using:
$ pip install -e .
Coding style¶
We follow the PEP8 coding style. Please note in particular:
- indentation of four spaces, no tabs
- single space around most operators, but no space around the ‘=’ sign when used to indicate a keyword argument or a default parameter value.
Testing¶
Running the PyNN test suite requires the nose package, and
optionally the coverage package. To run the entire test suite, in the
lib9ml/python/test
subdirectory of the source tree:
$ nosetests unit
To see how well the codebase is covered by the tests, run:
$ nosetests --with-coverage --cover-package=nineml --cover-erase --cover-html test/unittests
If you add a new feature to nineml
, or fix a bug, you should write a
unit test to cover the situation it arose.
Unit tests should where necessary make use of mock/fake/stub/dummy objects to isolate the component under test as well as possible.
Submitting code¶
The best way to get started with contributing code to NineML is to fix a small
bug (bugs marked “minor” in the bug tracker) in your checkout of
the code. Once you are happy with your changes, run the test suite again to
check that you have not introduced any new bugs. If this is your first
contribution to the project, please add your name and affiliation/employer to
lib9ml/python/AUTHORS
.
After committing the changes to your local repository:
$ git commit -m 'informative commit message'
first pull in any changes from the upstream repository:
$ git pull upstream master
then push to your own account on GitHub:
$ git push
Now, via the GitHub web interface, open a pull request.
Documentation¶
Python NineML documentation is generated using Sphinx.
To build the documentation in HTML format, run:
$ make html
in the doc
subdirectory of the source tree. Some of the files contain
examples of interactive Python sessions. The validity of this code can be
tested by running:
$ make doctest
Python NineML documentation is hosted at http://nineml-python.readthedocs.io/
Making a release¶
To make a release of NineML requires you to have permissions to upload Python NineML packages to the Python Package Index and the INCF Software Center. If you are interested in becoming release manager for Python NineML, please contact us via the mailing list.
When you think a release is ready, run through the following checklist one last time:
- do all the tests pass? This means running nosetests and make doctest as described above. You should do this on at least two Linux systems – one a very recent version and one at least a year old, and on at least one version of macOS.
- does the documentation build without errors? You should then at least skim the generated HTML pages to check for obvious problems.
- have you updated the version numbers in
setup.py
,__init__.py
,doc/source/conf.py
anddoc/source/installation.rst
?- have you written release notes and added them to the documentation?
Once you’ve confirmed all the above, create a source package using:
$ python setup.py sdist
and check that it installs properly (you will find it in the dist
subdirectory.
Now you should commit any changes, then tag with the release number as follows:
$ git tag x.y.z
where x.y.z
is the release number.
If this is a development release (i.e. an alpha or beta), the final step is to upload the source package to the INCF Software Center. Do not upload development releases to PyPI.
To upload a package to the INCF Software Center, log-in, and then go to the Contents tab. Click on “Add new…” then “File”, then fill in the form and upload the source package.
If this is a final release, there are a few more steps:
if it is a major release (i.e. an
x.y.0
release), create a new bug-fix branch:$ git branch x.yupload the source package to PyPI:
$ python setup.py sdist uploadmake an announcement on the mailing list
if it is a major release, write a blog post about it with a focus on the new features and major changes.