Patching guidelines

How to Create a Patch

To ease the committers' job it's best if you follow these guidelines when creating patches:

1. Create a separate environment with virtualenv (optional, see below) and activate it.
2. Checkout TurboGears from SVN and "python setup.py develop" it.

3. Configure Subversion in the following way:

   • Set enable-autoprops to yes.
   • Add *.pyc and *.pyo to the global-ignores patterns.
   • Add entries for common text file types to the auto-props section, so that their svn:eol-style property will be set to native.

   You can copy-and-paste the configuration snippet below to your Subversion configuration file.

4. Make your changes. If you are not sure, against which branch you should make your changes, ask on the mailing list. Please follow the projects's coding style.
5. A big plus will be awarded for those tickets implementing tests to make sure changes work as expected and prevent regressions. Docstrings and comments at the code will make future maintainers life easier. 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.
6. Run python setup.py test. All tests must pass.
7. 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.
8. Submit your patch (see below).

How to Submit a Patch

1. Post the issue to the mailing list (turbogears for bugs, turbogears-trunk for features).
2. Discuss it and determine whether it is really a bug/useful.
3. Create new ticket on Trac (you'll need to have a Trac account).

4. 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.

5. 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.
6. (Optional) Harass someone to make sure it gets accepted.

Setting up virtualenv

1. Install virtualenv from the Cheeseshop:

   [sudo] easy_install virtualenv

2. Create a new environment:

   virtualenv </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 elswhere on your system, and thus helps to make sure that you are not summiting a broken patch.

Subversion Configuration

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