wxTrac is now in read-only mode, please report wxWidgets issues on GitHub. You may also find all the existing tickets there using the same number as in wxTrac (except for the very old tickets).

Please post to wx mailing lists if you have any questions about wxTrac or GitHub Issues.


How to Submit Patches

TL;DR: Either use GitHub pull requests or submit a unified diff against the latest version of the appropriate branch (master or stable) and remember to update the docs and unit tests in any case.

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

If possible, i.e if you already use GitHub, please submit your patches via GitHub pull requests (PR) mechanism, i.e. fork wxWidgets repository, make a branch with your changes and submit PR to wx (master or 3.0). This has the advantage of building your patch in several different build configurations and rerunning the tests, so it's the preferred way of submitting your changes.

However even if you don't use GitHub and don't want to start using it, we still accept plain patches too. For those, please use the manual approach described here:

  • 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 the git master branch. If the bug is only in stable branch or it was already fixed in master, make the patch against the stable git branch. You can learn how to download the source from git here.

If you cannot access git (for example when you are behind a firewall), please make the patch against latest release or, better, against fresh git snapshot (latest download: master.zip).

  • Standard patch format: Please do NOT send us ZIP archives, whole files or even worse, only code snippets without context. It should be possible to apply your patch using a single patch -p1 < your.diff or patch -p0 < your.diff command.

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 git diff command which works almost in the same manner as diff if you are already using a git clone. The best way to make a patch is to use this command from the root wxWidgets directory:

git diff origin/master... > mypatch.patch

Alternatively, use the appropriate base git ref (i.e. for WX_3_0_BRANCH)

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 and 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 split 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 accommodate 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: If you submit your changes as a patch, and not as a GitHub PR, 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 17 months ago Last modified on Aug 23, 2020, 11:52:44 PM