How to Submit Patches

by Vaclav Slavik and Vadim Zeitlin (updated for svn by Axel Gembe)
Last update: July 18, 2007

User feedback and, especially, patches are very important for wxWidgets. They often help us improve wxWidgets' quality and fix bugs, so we are of course happy if you contribute them (how could we dislike your help, after all?). But we have all sort of problems with applying non-standard patches. To make life easier for both you and us, please follow the few simple rules below when submitting patches:

1. Do NOT send us ZIP archives, whole files or even worse, only code snippets. Patch is something that we could apply with one command, not arbitrary text that we'd spend hours trying to understand.

   The advantage of using diff is that it produces one file with differences in all files you modified and what's more, diff files are small, easy to read and understand and can be applied even if the affected files have been changed since the moment when the patch was submitted.

   The only exception to this rule is for the translations: unfortunately, .po files change a lot each time they are regenerated because all line numbers recorded in them change, and this risks making any patches to them unappliable very quickly. So for these files, and only for them, please submit the whole files and not patches to the existing ones. You can use diff program which is a standard part of most Unix systems and is available as part of cygwin package or elsewhere for Windows or, alternatively, you can just use svn diff command which works almost in the same manner as diff if you are already using SVN. The best way to make a patch is to use this command:

   svn diff > mypatch.patch

2. Always make you patches against latest version of wxWidgets. If your patch fixes a bug in stable branch, get the latest 2.8.X branch from SVN like this:

   svn checkout http://svn.wxwidgets.org/svn/wx/wxWidgets/branches/WX_2_8_BRANCH wxWidgets-2.8

   Make your changes against this version and create the patch like this:

   svn diff wxWidgets-2.8 > mypatch.patch

   This outputs the difference between the latest SVN version of 2.8 branch and your locally modified copy.

   If your patch adds new feature or fixes something in development version, make it against freshly checked out SVN tree (see here for instructions on how to access it). If you cannot access SVN (for example when you are behind a firewall), make the patch against latest release or, better, against fresh SVN snapshot (downloadable from here).

3. Notice that if your patch adds or removes files you should run svn add or svn remove before using svn diff if you're using svn for making the patch. And if you use a standalone diff program locally, you need to use -N option for the new files to be included in the patch.

4. Never edit the patch on a Windows system with an editor which can't handle/preserve the Unix like line termination.

5. Do not split single code change into multiple patch. A patch should be self-contained -- one patch for one thing. A patch that adds bitmaps to menu items and fixes a bug in wxHTML is a bad patch. It should be splitted into two patches. On the other hand, two patches, one of them being "implementation of new member-functions", the other "changes in class description to accomodate new members" are two bad patches. They are related to one, logically indivisible, thing, so they should be part of one patch. Also note that it is not possible to upload multiple files at once -- this is why you should use diff which produces one small file. Another example: if you adapted the build system to work on new, previously unsupported platform, we would gladly accept your patch. Just please send us single patch, not 10 patches, one for each modified file.

6. Please do not send the patches to the wxwindows-devel mailing list, nor to any developer's personal email address. Instead, use the Patch Manager at SourceForge. Then you will be notified when the patch is accepted or if there is a problem with applying the patch.

7. When you create new patch at SourceForge, please note that you MUST (this word should also be blinking but we'll spare you that) log in to SourceForge before submitting a patch as otherwise attaching the files will not work and, even worse, we won't be able to contact you to tell you about it nor any other potential problems with your patch!

   Also, please make sure you fill-in the form correctly. In particular, assign proper Category and write explanatory summary. Summaries like "Implementation of new member-functions" or just "ownerdrw.cpp" are useless as they don't tell us anything about what the patch does (and these examples are unfortunately real). They are, in fact, the best way how to upset poor overloaded developers. An example of proper summary is "Fixes build problem under OS Foo in bar.cpp" or "Fixes to wxFileHistory so that it doesn't show nonexistent files".

8. Describe the patch as precisely as possible in the Details field. Remember that it is often not easy to understand the purpose of your patch just from its source code. Alternatively, you may post a message explaining what your patch does to wxwindows-devel mailing list.

   If you provide detailed description of the patch, we will be able to apply it much faster -- and we will love you for submitting such nice patches :)

9. Please read the wxWidgets coding standards and try to conform to them. In particular, please respect the indentation rules (4 spaces, no TABs) as it makes really difficult to read the patches otherwise. Also, please remember to use wxT() macro around all literal strings and characters (i.e. wxT("Hello, world!"), wxT(':')) as it is a common error with usually fatal consequences for the Unicode build of the library.

10. Last but not least, if your patch adds a new feature please include the patch to the documentation as well as undocumented feature is hardly useful to anyone but its author. Doing this is described in this tech note but for the small patches the simplest and usually the best is to look at the existing documentation and update it to reflect your changes.

    Remember that if you don't do it, another developer would have to write the documentation and the patch won't be applied it until he has time to do it.