= Submitting Patches =

Have you made some changes you'd like to submit to Trac?  Great!  We'd love to see them.  However some people who are unfamiliar with the process of submitting changes make it overly complicated for themselves and the developers reviewing the changes.  So, in order to make things go smoothly for everyone, here are some guidelines on submitting your changes.

== What is a patch? ==

A patch is a single file listing the changes you've made in a format that can be applied with the [http://www.gnu.org/software/patch/ GNU patch] tool.  It will look something like this:
{{{
Index: /branches/0.9-stable/trac/scripts/admin.py
===================================================================
--- /branches/0.9-stable/trac/scripts/admin.py (revision 2822)
+++ /branches/0.9-stable/trac/scripts/admin.py (revision 3521)
@@ -12,9 +12,10 @@
 # history and logs, available at http://projects.edgewall.com/trac/.
 #
 
+from __future__ import generators
+
 __copyright__ = 'Copyright (c) 2003-2006 Edgewall Software'
 
-from __future__ import generators
 import cmd
 import getpass
 import os
}}}

Don't worry too much about the file format, since creating and using patches can all be done easily using the right tools.

== Getting started ==

First you'll need to get a copy of the Trac source to make and test your changes.  Use [http://subversion.tigris.org/ Subversion] to get the source so that you can easily generate your patch.

Bug fixes for a current release may be added on the "stable" branch:
{{{
svn checkout http://svn.edgewall.org/repos/trac/branches/0.9-stable trac-0.9-stable
}}}

Features should be added on the "trunk" development version:
{{{
svn checkout http://svn.edgewall.org/repos/trac/trunk trac-trunk
}}}

== Make some changes ==

Go ahead and make your changes to the Trac code.  Test them out.

== Adding files ==

Did you create any new files?  If you only modified existing Trac files you can skip this.  However, if you added any new files be sure to tell Subversion you're adding them:

{{{
svn add trac/my_new_file.py
}}}

== Make the patch ==

Simply run:
{{{
svn diff > my_patch_file.diff
}}}

This will save your changes to the file "my_patch_file.diff".  Pick an appropriate filename for the changes you've made.

== Submit the patch ==

If there is an existing ticket related to the changes you've made attach your patch file to that ticket.  Otherwise please create a new ticket and attach your patch file.  Be sure to provide a comment briefly explaining your changes.

Add the text "[PATCH]" at the beginning of the ticket's "Summary" field as a hint to developers that a possible patch has been provided.

----
See also: TracDev