Contributing to TurboGears 2

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. The TurboGears team page lists who is responsible for what (a little outdated don’t trust it much).

Installing

This is covered in the main Installation Documentation

Source Layout

TurboGears 2 is composed of two core packages.

  • tg package is TurboGears 2 core.
  • tg.devtools is a set of tools used for developing turbogears applications but not needed for running them.

Coding style

Since it’s hard to argue with someone who’s already written a code style document, TurboGears 2 follows PEP 8 conventions. The only rule we are do not enforce is the 80 characters per line, as templates and other web related files simply don’t fit into 80 chars in a natural way.

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 essential to make the future growth of the project as error free as possible.

TurboGears 2 uses Nose, which makes testing easy. You can run the tests in each of the source directories just by running nosetests. For example, to run the test on the TG2 server:

(tg2dev)$ cd tg2
(tg2dev)$ nosetests

Default options for nosetests can often be found in the [nosetests] section of setup.cfg and additional options can be passed on the command line. See the Nose documentation for details.

For TG2 projects all testing default are configured in it’s tests package for maximun user configurability.

Documenting Changes

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

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

These are generated with sphinx and normally include both TG docs and the sphinx sources of all upstream packages (that use sphinx)

Manual

The TurboGears 2 documentation is online at http://turbogears.org/2.0/docs/

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.

Contributing Documentation

Please see the TG1 guidelines for contributing documentation for pointers on documentation format and style.

Check out a copy of the documentation tree, edit the reStructured Text source files, and submit patches via tickets on the TurboGears Trac setting the ticket’s type to “Documentation” or an email to turbogears-docs, we’ll prefer patches for changes that modify old documents and a single file with the new document if it’s entirely new.

If you want to work on the docs sources and build the documentation tree you will also need:

Assuming that you’re going to work in a virtualenv called tg2dev, activate the virtualenv:

$ cd tg2dev
$ source bin/activate

(tg2dev) will be prefixed to your prompt to indicate that the tg2dev virtualenv is activated.

Check out the latest version of the docs sources from the subversion repositories:

(tg2dev)$ svn co http://svn.turbogears.org/docs

Build the documentation tree with:

(tg2dev)$ cd docs/2.0/docs
(tg2dev)$ make html

You can view the docs by pointing your browser at the file:

docs/2.0/docs/_build/html/index.html