Clone this wiki locally
How to contribute?
If you do not know git, there is some stuff to read before you can get started. We recommend that you start at “the github learning pages”http://learn.github.com/. It will point you to further resources where you can get help. There is a lot of different resources on the web – you can find most of them here.
You can find some typical git workflows on our git example page.
If you have made yourself familiar with git, you should check out github. Be sure to register and follow their tutorials on how to connect with github.
As soon as you have done that, you can fork our project pybrain/pybrain. You can then get a local clone and do your changes.
If you have pushed your changes to your fork, you can send pull requests to us via the github web interface. We will then try to incorporate your changes.
Before a pull request
Make sure that all tests pass and that your new code is sufficiently tested. Also make sure that your code plays well with our coding guidelines.
Getting involved with a new version control system always includes some time of learning. In some cases, people do not have the time or will to learn right away and first want to get their code running. In that case, you can always download the latest version here under “Download”. Do your changes in your local folder and send new versions (or even better, patches) to email@example.com.
Already have a clone but no github fork?
In some cases, you may already have a clone of the pybrain repository without a github account. In that case, fork the pybrain project as above on the github wegpage. Now go into your old clone and use
git remote add <your-username> <your-private-clone-url>. This adds your fork as a “remote”, from where you can pull from and push to changes. Then use
git merge <your-username> to merge in any changes since you first cloned the project. Afterwards, your local changes can be pushed to github
git push --all <your-username>.
The PyBrain project follows the Python style guide. Other than most Python projects,
we follow the “camelCase” way of naming classes and methods. Furthermore, every module should have a
__author__ variable at the top. It should include the authors’ names and email adresses.
If you haven’t done yet, configure your editor to remove trailing whitespaces and use proper newline endings: like amost every project, pyBrain uses only unix EOL.
At your option, you can also configure git for this just setting
core.autocrl option to
input . See the correspective Github Help page for more informations.
Since PyBrain is written in a dynamic language there is no type safety. This makes it hard to detect typing errors. Additionally to the usual benefits of writing tests, tests play a even more important role in collaborative development:
- You can check whether you messed up the code of someone else
- Others can check whether they messed up your code
If you do not write tests, changes to the core of the framework may break functionality in the upper levels and this may stay unnoticed for some time.
Running the tests
pybrain/tests/ $ runtests.py
to run all the tests. You can run tests more granulary by just executing any
Kinds of tests
Naming of test files
Test files are put in the
pybrain/tests/unittests folder. Naming testing files follows the convention to prefix them with
test_ and to use the underscore separated import path as the rest. Say you want to develop a module
pybrain.unsupervised.trainers.rbmtrainer. In that case, you’d put a file called
test_unsupervised_trainers_rbmtrainer.py in the test directory, where you write your tests in.
The naming conventions ensure that the tests are run when the whole test suite is run.
Layout of a test file
You can put any doctests and unittests in your test file as you like. Furthermore, the following lines are crucial:
from pybrain.tests import runModuleTestSuite if __name__ == "__main__": runModuleTestSuite(__import__('__main__'))
This assures that the test files can be run as simple scripts. For instance, you can run
trunk/pybrain/tests/unittests $ python test_unsupervised_trainers_rbmtrainer.py
in order to run tests specific to the rbm trainer.
You will of course need sphinx to build the documentation. The easiest way is via
easy_install. Just run
$ easy_install Sphinx
In case you don’t have easy_install, Python’s package manager, installed – run this script, which will install it for you in a bootstrapping manner.
Building the documentation
Now that Sphinx is on your system, you can go into the documentation directory for sphinx:
docs/sphinx/ and run
$ sphinx-build -b . .build/
which will create HTML documentation files for you in the
.build/ directory. Point your browser at
.build/index.html and you are set.