This page contains information for TurboGears :doc:`contributors </Contributing>` on how to create and submit patches to the TurboGears code. The instructions apply to developers with commit access to the TurboGears subversion repository as well as occasional contributors who submit patches through tickets or the mailing list.
To ease the committers' job it's best if you follow these guidelines when creating patches:
Create a separate environment with virtualenv (optional, but strongly recommended, see below) and activate it.
Checkout TurboGears from SVN, change into the root of directory of the branch you want to work on and do "python setup.py develop". You might need to install some extra dependencies for developers (ORMs, testing frameworks, etc.) manually with easy_install. See the setup.py file of TurboGears to see what they are.
Configure Subversion in the following way:
You can copy-and-paste the configuration snippet below to your Subversion configuration file.
Make your changes. If you are not sure, against which branch you should make your changes, ask on the mailing list.
All code should meet the following quality standards. If it doesn't, the TurboGears maintainers reserve the right to reject patches or revert commmits.
If a new file is created make sure to svn add it (even if you don't have commit access) so the diff takes it into account.
Run python setup.py test. All tests must pass.
If everything passes run "svn diff > my_patch.diff" from the root of your SVN checkout. This will create a unified diff of everything that changed into a single file.
Submit your patch (see below).
Discuss it and determine whether it is really a bug/useful.
Create new ticket on Trac (you'll need to have a Trac account).
Attach a patch and put [PATCH] in the title so it's easier to spot. Please also note which branch it was diffed against.
If you are not sure, which branch you should patch against, ask on the mailing list.
Check out the information above on how to create patches.
Post a follow-up in the mailing list discussion linking to your Trac ticket and get some people to test your patch and comment on it.
(Optional) Harass :doc:`someone </TurboGearsTeam>` to make sure it gets accepted.
Install virtualenv from the Cheeseshop:
[sudo] easy_install virtualenv
Create a new environment:
virtualenv --no-site-packages </path/to/new/environment> source </path/to/new/environment>/bin/activate
This is good because it will insure that you are running your svn copy and not a copy of TurboGears that might be installed elsewhere on your system, and thus helps to make sure that you are not summiting a broken patch.
Please copy-and-paste the following to your Subversion configuration. On Unix/ Mac OS X, this is ~/.subversion/config, for Windows, please refer to the Subversion documentation.
This configuration file will ensure that text files use the proper line-ending convention, regardless of the operating system you are using. Also, it will prevent you from involuntarily adding *.pyc and *.pyo files to the repository.
[miscellany] global-ignores = *.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#* .DS_Store *.pyc *.pyo enable-auto-props = yes ### Section for configuring automatic properties. [auto-props] ### The format of the entries is: ### file-name-pattern = propname[=value][;propname[=value]...] ### The file-name-pattern can contain wildcards (such as '*' and ### '?'). All entries which match will be applied to the file. ### Note that auto-props functionality must be enabled, which ### is typically done by setting the 'enable-auto-props' option. # source code *.c = svn:eol-style=native *.cpp = svn:eol-style=native *.dsp = svn:eol-style=CRLF *.dsw = svn:eol-style=CRLF *.h = svn:eol-style=native *.js = svn:eol-style=native *.py = svn:eol-style=native *.sh = svn:eol-style=native;svn:executable Makefile = svn:eol-style=native # text files *.cfg = svn:eol-style=native *.cfg_tmpl = svn:eol-style=native *.css = svn:eol-style=native *.html = svn:eol-style=native *.ini = svn:eol-style=native *.kid = svn:eol-style=native *.tmpl = svn:eol-style=native *.po = svn:eol-style=native *.py_tmpl = svn:eol-style=native *.rst = svn:eol-style=native *.txt = svn:eol-style=native *.txt_tmpl = svn:eol-style=native *.xml = svn:eol-style=native PKG-INFO = svn:eol-style=native MANIFEST.in = svn:eol-style=native README* = svn:eol-style=native # images *.png = svn:mime-type=image/png *.jpg = svn:mime-type=image/jpeg *.gif = svn:mime-type=image/gif