.. _dev_start_guide:

=====================
Developer Start Guide
=====================

To get up to speed, you'll need to

- Learn some non-basic Python to understand what's going on in some of the
  trickier files (like tensor.py).
- Go through the `NumPy documentation`_.
- Learn to write reStructuredText_ for epydoc_ and Sphinx_.
- Learn about how unittest_ and nose_ work

.. _Sphinx: http://sphinx.pocoo.org/
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _epydoc: http://epydoc.sourceforge.net/
.. _NumPy documentation: http://docs.scipy.org/numpy/
.. _unittest: http://docs.python.org/library/unittest.html
.. _nose: http://somethingaboutorange.com/mrl/projects/nose/

Accounts
--------

To obtain developer access: register with `GitHub
<http://www.github.com/>`_ and create a fork of `Theano
<http://www.github.com/Theano/Theano>`_.

Clone your fork locally with

.. code-block:: bash
    git clone git@github.com:your_github_login/Theano.git

and add a reference to the 'central' Theano repository with

.. code-block:: bash
    git remote add central git://github.com/Theano/Theano.git

When working on a new feature in your own fork, start from an up-to-date copy
of the trunk:

.. code-block:: bash
    git fetch central
    git checkout -b my_shiny_feature central/master

Once your code is ready for others to review, push your branch to your github fork:

.. code-block:: bash
    git push -u origin my_shiny_feature

then go to your fork's github page on the github website, select your feature
branch and hit the "Pull Request" button in the top right corner.
If you don't get any feedback, bug us on the theano-dev mailing list.

Details about ``PYTHONPATH``
----------------------------

``$PYTHONPATH`` should contain a ":"-separated list of paths, each of which
contains one or several Python packages, in the order in which you would like
Python to search for them. If a package has sub-packages of interest to you,
do **not** add them to ``$PYTHONPATH``: it is not portable, might shadow other
packages or short-circuit important things in its ``__init__``.

It is advisable to never import Theano's files from outside Theano itself
(this is good advice for Python packages in general). Use ``from theano import
tensor`` instead of ``import tensor``. ``$PYTHONPATH`` should only contain
paths to complete packages.

When you install a package, only the package name can be imported directly. If
you want a sub-package, you must import it from the main package. That's how
it will work in 99.9% of installs because it is the default. Therefore, if you
stray from this practice, your code will not be portable. Also, some ways to
circumvent circular dependencies might make it so you have to import files in
a certain order, which is best handled by the package's own ``__init__.py``.

More instructions
=================

Once you have completed these steps, you should run the tests like this:

.. code-block:: python

    >>> import theano
    >>> theano.test()

Or by running ``nosetests`` from your checkout directory.

All tests should pass. If some test fails on your machine, you are
encouraged to tell us what went wrong on the `theano-users`_
mailing list.

.. _theano-users: https://groups.google.com/group/theano-users

To update your library to the latest revision, you should have a branch
that tracks the main trunk. You can add one with:

.. code-block:: bash
    git fetch central
    git branch trunk central/master

Once you have such a branch, in order to update it, do:

.. code-block:: bash
    git checkout trunk
    git pull

Keep in mind that this branch should be "read-only": if you want to patch
Theano, do it in another branch like described above.

Nightly test
============

Each night we execute all the unit tests automatically.  The result is sent by
email to the `theano-buildbot`_ mailing list.

.. _theano-buildbot: https://groups.google.com/group/theano-buildbot

For more detail, see :ref:`see <metadocumentation_nightly_build>`.

