wiki:HowToSubmitPatches

How to Submit Patches

The bottom line: Attach an unified diff against svn trunk (or stable branch, when appropriate), remember to update docs and unit tests.

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.

Remember that if you have any questions about the steps here, you can always post them to wx-dev mailing list and we'll do our best to help you.

Changing wxWidgets

  • Follow the rules: 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.
  • Unit tests: Please update (or add) unit tests for any easily testable (i.e. non purely GUI) functionality that you modify or add. Our test suite doesn't cover 100% of wxWidgets code yet but we'd really like it to and we prefer not to add new classes or functions without tests.
  • Unicode strings: If your patch is against 2.8 branch, 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. Note that this does not apply to the trunk, where wxT() is neither necessary nor desirable anymore.
  • Documentation: 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. The API is documented in /interface directory, in familiar and simple Doxygen format. If you don't do it, another developer would have to write the documentation and the patch won't be applied until he has time to do it.

Mechanics of patch submission

  • Use the latest version: Please try to always make your patches against the latest version of wxWidgets.

In most cases, you should make a patch against SVN trunk. If the bug is only in stable branch or it was already fixed in the trunk, make the patch against the stable SVN branch. You can learn how to download the source from SVN here.

If you cannot access SVN (for example when you are behind a firewall), please make the patch against latest release or, better, against fresh SVN snapshot (downloadable from here).

  • Standard patch format: 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 from the root wxWidgets directory:

svn diff > mypatch.patch

or this one from the parent directory

svn diff wxWidgets-2.8 > mypatch-for-stable-branch.patch

If you use a standalone diff you need to add the -u option, i.e.:

diff -uNr wxWidgets-orig wxWidgets-mine > mypatch.patch

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.

  • Use standard extension .diff or .patch for the patch file: Trac is capable of displaying the attachments with these extensions directly in the web interface which is very useful for the initial examination.
  • Don't include auto-generated files (wx/{msw,univ}/setup.h, Makefiles, etc.) in the patch.

The simplest way is to edit the patch and remove appropriate chunks. Alternatively, please see this post about how to do it on a Unix system (including Cygwin).

  • Make atomic patches: Do not split single code change into multiple patches. 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.

Submitting the patch

  • Use Trac: Please do not send the patches to the wx-dev mailing list, nor to any developer's personal email address. Instead, use the tracker. Then you will be notified when the patch is accepted or if there is a problem with applying the patch.
  • Describe your changes: Please fill in the ticket form according to HowToSubmitTicket and describe the patch as precisely as possible in the Description 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 wx-dev 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 :)

  • Let us know your name: Concerning the latter, we'd also like to give you credit for your patch (unless it's something really trivial as we avoid mentioning very small changes in our changelog) but we need to know your real name for this. Please tell us about it if we don't know you already from your posts to wx-dev.

Thank you for reading this document -- and looking forward to your patches!

Last modified 3 years ago Last modified on 03/29/12 06:36:10