Contributing to TurboGears

If you want to help out, we want to help you help out! The goal of this document is to help you get started and answer any questions you might have. The Project Philosophy document has a more high-level view, whereas this document is nuts-and-bolts.

Subversion

The TurboGears subversion repository is here:

http://www.turbogears.org/svn/turbogears

In typical Subversion style, the current development is happening on the trunk:

http://www.turbogears.org/svn/turbogears/trunk

To check out the trunk, you would typically use the command:

svn co http://www.turbogears.org/svn/turbogears/trunk turbogears

This will give you a "turbogears" directory with the trunk in it.

You can get the basic Subversion clients from the official Subversion site, and graphical clients are available for just about any platform. The Version Control with Subversion book is available for reading online.

Development Prerequisites

To work with TurboGears 0.9 code that is now in development, you'll need to install the RuleDispatch package. The easiest way to do this is to run the following command from the top level directory of your TurboGears checkout:

easy_install RuleDispatch

(Note that the usual caveats about sudo and such apply.)

Developing with eggs

TurboGears (and even projects that TurboGears creates via quickstart) uses setuptools to make packaging and distribution much easier.

To start developing on TurboGears itself, you'll want to go into your checked-out copy and run:

python setup.py develop

That command tells setuptools that you're going to be using that code for TurboGears, rather than any installed TurboGears egg you might have.

Coding style

Since it's hard to argue with someone who's already written a code style document, TurboGears will follow PEP 8 conventions.

Testing

Automated unit tests are better than good. They make future growth of the project possible.

TurboGears uses TestGears, which makes testing easy. Other tools and functions that make testing easy are welcomed.

Documentation

As mentioned in the Project Philosophy document, a feature doesn't truly exist until it's documented. Tests can serve as good documentation, because you at least know that they're accurate. But, it's also nice to have some information in English.

There are two kinds of docs, and both have their useful place. A modified epydoc (which includes links to the source) is used to generate API docs for the website. It's not very taxing at all to add these doc strings as you work on the code.

Additionally, the high-level documentation is located in the docs directory. Those are the source files for the TurboGears.org website. Each of these files is an XHTML Kid template. Diagrams, source code syntax highlighting, etc. are all much appreciated in there.