Contributing to TurboGears

Development Status

To read about the latest status of development of the different TurboGears branches, please read the TurboGears Development Status page.

Subversion

The TurboGears subversion repository is at http://svn.turbogears.org/.

You can also browse the repository via the TurboGears Trac.

There are currently three branches where development is being done:

• the 1.0 branch where the current 1.0 release is maintained.
• the 1.1 branch where the next major release of TG is prepared.
• the trunk, where the new TG 2.0, based on Pylons, is in development.

Note that the trunk may break at any time so don't run it unless you know what you are doing.

To check out the 1.0 branch, you would typically use the command:

svn co http://svn.turbogears.org/branches/1.0 turbogears

To check out the 1.1 branch, do:

svn co http://svn.turbogears.org/branches/1.1 turbogears

Or to check out the trunk:

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

This will give you a "turbogears" directory with either the 1.0 branch, the 1.1 branch or 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.

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.

Dealing with Dependencies

It is not uncommon between releases of TurboGears that projects used by TurboGears will be upgraded. For the core projects used by TurboGears, there are svn:externals defined to check out the appropriate version of the projects in the thirdparty directory. When projects are upgraded, the setup.py file is also changed to reflect the new version that is required to use TurboGears.

If you get an error about a requirement not being met when running a development copy of TurboGears, you will generally be able to satisfy the requirement by going into the thirdparty directory and running:

python -c "import setuptools; execfile('externals.py')" develop

Alternatively, you can run:

easy_install .

which will give you a snapshot installation that doesn't track each svn update.

If you plan to make changes to one of the projects that TurboGears uses, make sure that you've got Subversion pointing to an appropriate version of that project for making changes (often the trunk). With the correct version in place, you can run "python setup.py develop" in that project to start using the development version of that tool.

Coding style

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

To ensure that files in the TurboGears source code repository have proper line-endings, you must configure your Subversion client. Please see the patching guidelines for details.

Testing

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

TurboGears uses Nose, which makes testing easy. To get going with Nose, just run:

easy_install nose

(As with all easy_install commands, you may need to use the -- script-dir option to tell it where to put the command line tool and you may need to use "sudo" on Unix-like systems to access that directory.)

Once installed, you can run the TurboGears tests just by running:

nosetests

The turbogears.testutil package includes some utility functions and classes that make you're life easier as you're trying to test.

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:

API reference

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. See the API reference for version 1.0 here.

Manual

The TurboGears documentation is maintained on the docs.turbogears.org wiki. If you want to work on the documentation in the wiki, please read the guidelines for contributing documentation.

When you contribute a new doc in the wiki, please write a page in the appropriate RoughDocs section of the site (e.g. for TurboGears version 1.1, you'd link it up from1.1/RoughDocs). One of the documentation editors will then pull your document into the official documentation, possibly doing a bit of editing in the process so that the style and tone match the rest of the official documents.

Please document your own work. It doesn't have to be Shakespeare, but the editors don't enjoy writing documentation any more than you do (we'd rather be coding) and it's much easier to edit an existing doc than it is to figure out your code and write something from scratch.

Documenting Changes

The Trac is mostly used for tracking upcoming changes and tasks required before release of a new version. The changelog provides the human readable list of changes.

Updating the changelog right before a release just slows down the release. Please update the changelog as you make changes, and this is especially critical for backwards incompatibilities.

How to Submit a Patch

Please make sure that you read and follow the patching guidelines.