Guidelines

How to contribute?

Using git

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.

Bypassing git

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 coredev@python.org.

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

Guidelines

Code conventions

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.

Spaces and EOL

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.

Testing

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

Run

pybrain/tests/ $ runtests.py

to run all the tests. You can run tests more granulary by just executing any test_*.py file in pybrain/tests/unittests/.

Kinds of tests

There are several introductions to writing tests in Python. You can write unittests or doctests, which is more common in PyBrain.

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.

Documentation

Pybrain uses Sphinx as its documentation tool, which is the same Python is using for version 2.6. You can find the current version on the project homepage.

Dependencies

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.