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
There are two branches of where development are being done, the 1.0 branch where the upcoming 1.0 release and future bugfixes will be cut from, and the trunk where the work for 1.1 is being done. 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://www.turbogears.org/svn/turbogears/branches/1.0/ turbogears
To check out the trunk
svn co http://www.turbogears.org/svn/turbogears/trunk turbogears
This will give you a "turbogears" directory with either the 1.0 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.
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 -f http://peak.telecommunity.com/snapshots/ 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.
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('setup.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.
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. 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.
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.
