Changes between Version 11 and Version 12 of HowToSubmitPatches


Ignore:
Timestamp:
Feb 15, 2012, 4:23:46 PM (8 years ago)
Author:
vadz
Comment:

Mention making patches from root directory and other minor enhancements

Legend:

Unmodified
Added
Removed
Modified
  • HowToSubmitPatches

    v11 v12  
    1616
    1717== Mechanics of patch submission ==
    18  * '''Use the latest version''': Please always make your patches against the latest version of wxWidgets.
     18 * '''Use the latest version''': Please try to always make your patches against the latest version of wxWidgets.
    1919
    20   In most of the 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 [http://www.wxwidgets.org/develop/svn.htm#setup here].
     20  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 [http://www.wxwidgets.org/develop/svn.htm#setup here].
    2121
    22   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 [http://wxwindows.sourceforge.net/snapshots/ here]).
     22  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 [http://wxwindows.sourceforge.net/snapshots/ here]).
    2323
    2424 * '''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.
    2525
    26   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:
     26  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:
    2727
    2828  `svn diff > mypatch.patch`
    2929
    30   or
     30  or this one from the parent directory
    3131
    3232  `svn diff wxWidgets-2.8 > mypatch-for-stable-branch.patch`
     
    3838  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.
    3939
    40  * Use standard '''extension .diff or .patch''' for the patch file.
     40 * 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.
    4141
    4242 * '''Don't include auto-generated files''' (wx/{msw,univ}/setup.h, Makefiles, etc.) in the patch.
    4343
    44   The simplest way is to edit the patch and remove appropriate chunks.
     44  The simplest way is to edit the patch and remove appropriate chunks. Alternatively, please see [http://wxwidgets.blogspot.com/2011/08/cleaning-patches-for-review.html this post] about how to do it on a Unix system (including Cygwin).
    4545
    4646 * '''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.