Contributing to TurboGears 2¶
| status: | Official |
|---|
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.
Installing the Development Version of Turbogears 2 (from source)¶
Pre-requisites¶
Python 2.4, 2.5, or 2.6 (http://python.org/download)
Make sure that your Python installation includes the sqlite extension (some *BSDs keep it in a separate package). If you’re running Python 2.5 you can test for sqlite with:
$ python -c "import sqlite3"
or try:
$ python -c "import pysqlite2"
with Python 2.4.
For RPM-based systems you will also need python-devel and python-xml packages.
On ubuntu you will need python-dev and python-setuptools.
-
run http://peak.telecommunity.com/dist/ez_setup.py from any directory
if you have an older version you can run:
$ easy_install -U setuptools
Warning
you need at least version 0.6c9 or some packages may fail installing, this is specially important if you have subversion 1.5.*
$ python >>> import setuptools >>> setuptools.__version__ '0.6c9'
-
- All mayor linux distributions have this, it’s normally named subversion, on windows you can download their exe installer
We recommend working in a virtual environment so that any existing packages will not interfere with your installation, and so that you don’t upgrade any Python libraries that your system needs.
Installing TurboGears 2 from Source¶
TurboGears 2 is composed of 2 packages. You also need 2 more package with are the authorization framework
Check out the latest code from the subversion respositories:
(tg2dev)$ cd ..
(tg2dev)$ svn co http://svn.turbogears.org/projects/tg.devtools/trunk tgdev
(tg2dev)$ svn co http://svn.turbogears.org/trunk tg2
(tg2env)$ svn co http://svn.repoze.org/repoze.what/trunk/ repoze.what
(tg2env)$ svn co http://svn.repoze.org/repoze.what/plugins/sql/trunk repoze.what.plugins.sql
There are also several dependencies, which can be easy_installed from our package index.
- tgdev is a set of tools, paster command plugins to create default template, admin interface, and migrations.
- tg2 package is TurboGears 2 core.
- repoze.what formelly tg.authorization is the Authorization framework
- repoze.what.plugins.sql is the default SQL plugin to work with TG auth model
Again, tell setuptools to use these versions.
- repoze.what:
(tg2dev)$ cd repoze.what
(tg2dev)$ easy_install zope.interface
(tg2dev)$ python setup.py develop
(tg2dev)$ cd ..
(tg2dev)$ cd repoze.what.plugins.sql/
(tg2dev)$ python setup.py develop
- TurboGears 2 server:
(tg2dev)$ cd ..
(tg2dev)$ cd tg2
(tg2dev)$ python setup.py develop
- TurboGears 2 developer tools:
(tg2dev)$ cd ..
(tg2dev)$ cd tgdev
(tg2dev)$ python setup.py develop
Congratulations! You now have a source installation of TurboGears 2. Happy Hacking!
Note
if you have installed old dependency packages, you could remove them from {python_path}/site-packages/easy-install.pth
Troubleshooting¶
It is possible (but not likely) you might see a few other error messages. Here are the correct ways to fix the dependency problems so things will install properly.
- When installing on Mac OSX, if you get an error mentioning No local packages or download links found for RuleDispatch, you can try the solution posted to the ToscaWidgets discussion list which advises downloading it directly:
(tg2dev)$ sudo easy_install -U -f http://toscawidgets.org/download/wo_speedups/ RuleDispatch
Coding style¶
Since it’s hard to argue with someone who’s already written a code style document, TurboGears 2 follows 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 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, the tg.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 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.
To contribute documentation you can either:
- Write a page in the RoughDocs section of the TurboGears documentation wiki and request a review of it on the turbogears-docs discussion list. 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 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
If you want to work on the docs sources and build the documentation tree you will also need:
pysvn is a Python extension that comes in source or binary kits to match your OS, Python version, and Subversion version. Please see the pysvn extension downloads page for details and follow the instructions there to install the appropriate version.
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 soruces from the subversion respositories:
(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
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.
