developers_guide.rst 6.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223
  1. =================
  2. Developers' guide
  3. =================
  4. These instructions are for developing on a Unix-like platform, e.g. Linux or
  5. Mac OS X, with the bash shell. If you develop on Windows, please get in touch.
  6. Mailing lists
  7. -------------
  8. General discussion of Elephant development takes place in the `NeuralEnsemble Google
  9. group`_.
  10. Discussion of issues specific to a particular ticket in the issue tracker should
  11. take place on the tracker.
  12. Using the issue tracker
  13. -----------------------
  14. If you find a bug in Elephant, please create a new ticket on the `issue tracker`_,
  15. setting the type to "defect".
  16. Choose a name that is as specific as possible to the problem you've found, and
  17. in the description give as much information as you think is necessary to
  18. recreate the problem. The best way to do this is to create the shortest possible
  19. Python script that demonstrates the problem, and attach the file to the ticket.
  20. If you have an idea for an improvement to Elephant, create a ticket with type
  21. "enhancement". If you already have an implementation of the idea, open a pull request.
  22. Requirements
  23. ------------
  24. See :doc:`install`. We strongly recommend using virtualenv_ or similar.
  25. Getting the source code
  26. -----------------------
  27. We use the Git version control system. The best way to contribute is through
  28. GitHub_. You will first need a GitHub account, and you should then fork the
  29. repository at https://github.com/NeuralEnsemble/elephant
  30. (see http://help.github.com/fork-a-repo/).
  31. To get a local copy of the repository::
  32. $ cd /some/directory
  33. $ git clone git@github.com:<username>/elephant.git
  34. Now you need to make sure that the ``elephant`` package is on your PYTHONPATH.
  35. You can do this by installing Elephant::
  36. $ cd elephant
  37. $ python setup.py install
  38. $ python3 setup.py install
  39. but if you do this, you will have to re-run ``setup.py install`` any time you make
  40. changes to the code. A better solution is to install Elephant with the *develop* option,
  41. this avoids reinstalling when there are changes in the code::
  42. $ python setup.py develop
  43. or::
  44. $ pip install -e .
  45. To update to the latest version from the repository::
  46. $ git pull
  47. Running the test suite
  48. ----------------------
  49. Before you make any changes, run the test suite to make sure all the tests pass
  50. on your system::
  51. $ cd elephant/test
  52. With Python 2.7 or 3.x::
  53. $ python -m unittest discover
  54. $ python3 -m unittest discover
  55. If you have nose installed::
  56. $ nosetests
  57. At the end, if you see "OK", then all the tests
  58. passed (or were skipped because certain dependencies are not installed),
  59. otherwise it will report on tests that failed or produced errors.
  60. Writing tests
  61. -------------
  62. You should try to write automated tests for any new code that you add. If you
  63. have found a bug and want to fix it, first write a test that isolates the bug
  64. (and that therefore fails with the existing codebase). Then apply your fix and
  65. check that the test now passes.
  66. To see how well the tests cover the code base, run::
  67. $ nosetests --with-coverage --cover-package=elephant --cover-erase
  68. Working on the documentation
  69. ----------------------------
  70. The documentation is written in `reStructuredText`_, using the `Sphinx`_
  71. documentation system. To build the documentation::
  72. $ cd elephant/doc
  73. $ make html
  74. Then open `some/directory/elephant/doc/_build/html/index.html` in your browser.
  75. Docstrings should conform to the `NumPy docstring standard`_.
  76. To check that all example code in the documentation is correct, run::
  77. $ make doctest
  78. To check that all URLs in the documentation are correct, run::
  79. $ make linkcheck
  80. Committing your changes
  81. -----------------------
  82. Once you are happy with your changes, **run the test suite again to check
  83. that you have not introduced any new bugs**. Then you can commit them to your
  84. local repository::
  85. $ git commit -m 'informative commit message'
  86. If this is your first commit to the project, please add your name and
  87. affiliation/employer to :file:`doc/source/authors.rst`
  88. You can then push your changes to your online repository on GitHub::
  89. $ git push
  90. Once you think your changes are ready to be included in the main Elephant repository,
  91. open a pull request on GitHub (see https://help.github.com/articles/using-pull-requests).
  92. Python 3
  93. --------
  94. Elephant should work with Python 2.7 and Python 3.
  95. So far, we have managed to write code that works with both Python 2 and 3.
  96. Mainly this involves avoiding the ``print`` statement (use ``logging.info``
  97. instead), and putting ``from __future__ import division`` at the beginning of
  98. any file that uses division.
  99. If in doubt, `Porting to Python 3`_ by Lennart Regebro is an excellent resource.
  100. The most important thing to remember is to run tests with at least one version
  101. of Python 2 and at least one version of Python 3. There is generally no problem
  102. in having multiple versions of Python installed on your computer at once: e.g.,
  103. on Ubuntu Python 2 is available as `python` and Python 3 as `python3`, while
  104. on Arch Linux Python 2 is `python2` and Python 3 `python`. See `PEP394`_ for
  105. more on this.
  106. Coding standards and style
  107. --------------------------
  108. All code should conform as much as possible to `PEP 8`_, and should run with
  109. Python 2.7 and 3.2-3.5.
  110. Making a release
  111. ----------------
  112. .. TODO: discuss branching/tagging policy.
  113. .. Add a section in /doc/releases/<version>.rst for the release.
  114. First check that the version string (in :file:`elephant/__init__.py`, :file:`setup.py`,
  115. :file:`doc/conf.py` and :file:`doc/install.rst`) is correct.
  116. To build a source package::
  117. $ python setup.py sdist
  118. To upload the package to `PyPI`_ (if you have the necessary permissions)::
  119. $ python setup.py sdist upload
  120. .. should we also distribute via software.incf.org
  121. Finally, tag the release in the Git repository and push it::
  122. $ git tag <version>
  123. $ git push --tags upstream
  124. .. make a release branch
  125. .. _Python: http://www.python.org
  126. .. _nose: http://somethingaboutorange.com/mrl/projects/nose/
  127. .. _neo: http://neuralensemble.org/neo
  128. .. _coverage: http://nedbatchelder.com/code/coverage/
  129. .. _`PEP 8`: http://www.python.org/dev/peps/pep-0008/
  130. .. _`issue tracker`: https://github.com/NeuralEnsemble/elephant/issues
  131. .. _`Porting to Python 3`: http://python3porting.com/
  132. .. _`NeuralEnsemble Google group`: http://groups.google.com/group/neuralensemble
  133. .. _reStructuredText: http://docutils.sourceforge.net/rst.html
  134. .. _Sphinx: http://sphinx.pocoo.org/
  135. .. _numpy: http://www.numpy.org/
  136. .. _quantities: http://pypi.python.org/pypi/quantities
  137. .. _PEP394: http://www.python.org/dev/peps/pep-0394/
  138. .. _PyPI: http://pypi.python.org
  139. .. _GitHub: http://github.com
  140. .. _`NumPy docstring standard`: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
  141. .. _`virtualenv`: https://virtualenv.pypa.io/en/latest/