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 ​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

This format is called an "unified diff format". See below how to generate it.

Getting started

First you'll need to get a copy of the Trac source to make and test your changes. Use ​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.12-stable trac-0.12-stable

Features should be added on the "trunk" development version:

svn checkout http://svn.edgewall.org/repos/trac/trunk trac-trunk

See how to setup a development environment.

Make some changes

Go ahead and make your changes to the Trac code.

It is a good idea to be familiar with the CodingStyle of the Trac project, so that we won't ask you to rework your changes later on.

Test the changes using tracd.

Ideally, you should write some tests (UnitTests or FunctionalTests) demonstrating the problem you're trying to address - the tests should fail before the fix and pass with your changes. Also, by running the tests, you will see if you didn't break anything else with your changes.

A sentence like added some more tests - all tests pass in your commit message is guaranteed to earn you good points from the maintainers ;-)

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.

Note that svn diff will generate a diff in the unified format. If for some reason you use the diff tool to produce the patch, then please use diff -u otherwise the diff won't be an unified diff.

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.

You may 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.

After that, depending on lots of factors, your patch will be reviewed and eventually integrated. Most probably, you'll be asked to rework your patch a bit, according to the preferences of the Trac maintainers.

If you wonder why your patch didn't get applied as fast as you'd liked to, see for example the case of #8883. Executive summary: while you never have any guarantee that a patch will be integrated, you can influence this outcome by making the developers want to integrate your patch. For this, read on to the next section.

What is a good patch?

Now, having written a patch is no guarantee that the change will actually make it into the repository. The patch has to be endorsed by a Trac developer, who will carry the burden to maintain that change over time. So the patch has to be convincing on different accounts:

• clarity
  • no spurious changes like whitespace change or other random reformattings
  • no unrelated changes; if some refactoring really needs to be done as a preliminary to the actual change, better do that in a separate patch
  • strict adherence to the CodingStyle
• maintainability
  • comments for the parts that needs to be commented, no more, no less
  • add UnitTests or FunctionalTests
  • make sure existing tests still pass with your change applied
• and of course, the quality of the code, the pertinence of the fix or the feature is the main criterion

That can be hard to get right the first time, so you'll certainly get asked to improve your patch. You should be willing to take feedback into account and maybe do a few iterations of the patch, if needed.

Also useful reading: ​Mercurial:SuccessfulPatch#How_to_describe_your_successful_patch.