Changes between Version 14 and Version 15 of HowToSubmitPatches


Ignore:
Timestamp:
Feb 13, 2017, 11:50:18 PM (7 months ago)
Author:
vadz
Comment:

Mention GitHub PRs as an alternative patch submission mechanism

Legend:

Unmodified
Added
Removed
Modified
  • HowToSubmitPatches

    v14 v15  
    11= How to Submit Patches =
    22
    3 '''The bottom line:''' Attach an unified diff against the git master branch (or stable branch, when appropriate), remember to update docs and unit tests.
     3'''TL;DR:''' Either use [https://help.github.com/articles/about-pull-requests/ 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.
    44
    55User 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.
     
    1919== Mechanics of patch submission ==
    2020
     21You have a choice between using GitHub pull requests (PR) mechanism or creating patches manually, at your convenience. If you already use GitHub, please feel free to open PRs to wxWidgets/wxWidgets repository there. If you don't want to start using it, please use the manual approach described here:
     22
    2123 * '''Use the latest version''': Please try to always make your patches against the latest version of wxWidgets.
    2224
     
    2527  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: [https://github.com/wxWidgets/wxWidgets/archive/master.zip master.zip]).
    2628
    27  * '''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.
     29 * '''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.
    2830
    2931  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:
     
    4547  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).
    4648
    47  * '''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.
     49 * '''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.
    4850
    4951== Submitting the patch ==
     
    5153 * '''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. Alternatively, we will also accept GitHub pull requests, however, we still prefer patches submitted to Trac.
    5254
    53  * '''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.
    54 
    55   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 :)
     55 * '''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 :)
    5656
    5757 * '''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.