Dear new MDP developer, we’ll try here to summarize some policies
and best-practices we’d like any MDP contributor to follow.

- Create an account on sourceforge.net and tell us your username
  there, so that we can add you to the list of developers and give
  you access to our git repositories

- Since our migration to git, the repository setup consists of
  four separate repositories:

  * mdp-toolkit
  * docs
  * examples
  * contrib

- Please only commit code in contrib repository.
  If your code contributions should need modification somewhere else
  in the MDP code base, write to
  mdp-toolkit-devel@lists.sourceforge.net
  for assistance and instructions how to proceed.
  For simple fixes that don’t need much discussion, you can also send
  a mail patch to the list using ‘git format-patch’ or similar.
  
- The only exception to the previous rule are the tests for your code. They
  should be added in 
  mdp-toolkit/mdp/test/test_contrib.py
  or in some yet-to-be-defined place in the contrib repository.
  Look how other contrib nodes are tested in the ContribTestSuite
  class in this file, and make sure your tests fit within that
  framework. Be particularly aware of the automatic testing of
  setting and consistency of input_dim, output_dim and dtype.
  
- If you are about to test something and you’ve got the idea that your
  code won’t last long in the repository, (maybe you want to show your
  code to another developer or you want to just check, if you can commit
  to the server,) you should create another branch for that.
  The branch should be prefixed by an identifier such as your initials, so
  that we can distinguish between all the ‘testing’ branches.

  The advantage is, that it keeps our master branch clean from all those
  ‘testing some really strange new stuff – please have a look’ commits, which
  are likely to be reverted again. When you feel good about your commit, you
  can cherry-pick or merge the good stuff to master.

  When you’re done with testing, it’s all right to delete the branch again
  from the server, in order to reduce the repository size and branch clutter.
  However, one must be careful with this, so only delete online branches when
  you know what you’re doing.
  If you want to introduce a huge change, you’re welcome to do this on an
  external public repository; that way only those developers interested
  in your changes will need to download it.

- If you want to develop on a Windows system you might run into some issues
  with git. Here is what we use for git on Windows:
  
  * Install the msysgit git client.
  * If you don't like working on the command line there are several graphical
	user interfaces available, the commercial SmartGit currently seems
    to work best (there is a free version for non-commercial use).
	
  If you want to use the Eclipse IDE (with PyDev) here is what you can do:
  
  * You can install the EGit plugin for Eclipse, but this is not yet stable. So
    you might want to use the command line or SmartGit for most actions.
  * Create a new PyDev project for each MDP git repo you want to work on. Clone
    the git repository to some arbitrary location and then move all the content
	(including the hidden .git folder) to the root of the corresponding project
	(EGit currently will not work if the .git is in some subdirectory).
  * Right-click on the project and select Team -> share to connect the git
    information to EGit.

- Remember to set the supported dtypes for your nodes.
  Example of a node supporting only single and double precision:
  SFANode in mdp-toolkit/mdp/nodes/sfa_nodes.py
  Example of a node supporting almost every dtype:
  HitParadeNode in mdp-toolkit/mdp/nodes/misc_nodes.py

- If setting input_dim, output_dim or dtype has side effects, remember to
  implement that in the _set_input_dim, _set_output_dim, _set_dtype
  functions. 
  Several examples are available in 
  mdp-toolkit/mdp/nodes/

- Your code contribution should not have any additional
  dependencies, i.e. they should require only the numpy module to be
  installed. If your code requires some other module, e.g. scipy or
  C++ compilation, ask
  mdp-toolkit-devel@lists.sourceforge.net
  for assistance.
  
- Your code should strictly follow the PEP 8 coding convenctions
  (http://www.python.org/dev/peps/pep-0008/). Note that some older code
  sections in MDP do not follow PEP 8 100%, but when the opportunity arrises
  (e.g., when we make changes in the code) we are improving this. So new code
  should always follow PEP 8. Additional style guidelines can be learned from
  the famous 'Code like a Pythonista' presentation at
  http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html.
  
- Always import numpy in your code as 
  from mdp import numx
  "numx" is a placeholder we use to automatically import scipy
  instead of numpy when scipy is installed on the system.

- Only raise NodeException. If you need custom exceptions, derive
  them from mdp.NodeException

- Your nodes needs to pass the automatic tests for setting and
  consistency of input_dim, output_dim and dtype *and* at least one
  functional test, which should test the algorithm possibly in a
  non-trivial way and compare its results with exact data you can
  derive analytically. If the latter is not possible, you should
  compare results and expected data within a certain precision. Look
  for example at testPCANode in mdp-toolkit/mdp/test/test_nodes.py .

- You nodes must have telling and explicit doc-strings. In
  particular, the class doc-string must cite references (if any) for
  the algorithm, and list the internal attributes of interest for
  the user. Any method not belonging to the base Node class must be
  clearly documented in its doc-string. Error messages must give an
  hint to the user what’s wrong and possible ways around the
  problem. Any non trivial algorithmic step in the code must be
  commented, so that other developers understand what’s going on. If
  you have doubts, mark the code with 
  
  #???
  
  If you think a better implementation is possible or additional
  work is needed, mark the code with
  
  #TODO

  Have a look at the SFANode implementation for an example.

- When you commit your code *always* provide a meaningful log
  message: it will be mailed automatically to all other developers!

- This list is far from being complete, please let us know your
  comments and remarks :-)
 
