[r7423]: docs / wiki / patching_guidelines.rst Maximize Restore History

Download this file

patching_guidelines.rst    200 lines (144 with data), 7.2 kB

Patching Guidelines

Status:Official

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.

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, but strongly recommended, see below) and activate it.

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

  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.

  5. All code should meet the following quality standards. If it doesn't, the TurboGears maintainers reserve the right to reject patches or revert commmits.

    1. Please follow the projects's coding style (in a nutshell: follow PEP8).
    2. Document your code with docstrings for modules, classes, methods and functions and source code comments for code, which does things that are not immediately obvious to someone reading the code. Docstrings and source comments will make the life of future maintainers much easier. Please follow PEP257 conventions for docstrings and see the file doc/README.txt in your checkout or further hints.
    3. Add unit tests to the turbogears.tests sub-package for your changes. This is important for (at least) two reasons: a) it will protect against regressions and b) it will document how your code should be used and what it is supposed to do. See the :doc:`Testing </1.0/Testing>` page for more information about unit tests.
  6. 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.

  7. Run python setup.py test. All tests must pass.

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

  9. Submit your patch (see below).

How to Submit a Patch

  1. Post the issue to the :doc:`mailing list </GettingHelp>` (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 :doc:`someone </TurboGearsTeam>` 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 --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.

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