|
 How to submit patches to wxWidgets
by Vaclav Slavik and Vadim Zeitlin
Last update: February 19, 2005
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:
- 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
cvs diff command which works almost in the same manner as
diff if you are already using the cvs.
The best way to make a patch is to use this command:
cvs diff -u > mypatch.patch
However, for this to work you should be online. If you are offline
you can also type this command one level above your wxWidgets'
root directory:
diff -ru -x"CVS" -x".#*" -x"*.orig" -x"*.rej" -x"*~"
wxWidgets.orig wxWidgets > mypatch.patch
where wxWidgets.orig is the unmodified wxWidgets tree and
wxWidgets is your patched copy. Note that you shouldn't speciify
the r (recursive) switch when using cvs as it operates
recursively by default. You may also prefer to give explicitly the
names of the files you had modified as the command would run much
faster then.
Also, unless really, really impossible, please read diff's
documentation so that you know what you are doing. However, just in
case, a brief explanation: as we strongly prefer the universal
diffs, you should use the u switch. 2 after it
means to generate diffs with 2 lines of context and, finally,
the x options tell diff to exclude temporary and backup files as
well as the files private to the cvs itself.
- Always make you patches against latest version of wxWidgets.
If your patch fixes a bug in stable branch, make your patch
against the latest 2.2.X release. If you work with CVS, you can
do that with single command:
cvs diff -r WX_2_2_BRANCH
This outputs the difference between the latest CVS version of 2.2
branch and your locally modified copy.
If your patch adds new feature or fixes something in development
version, make it against freshly checked out CVS tree (see
wxWidgets website for instructions on how to access it).
If you cannot access CVS (for example when you are behind a
firewall), make the patch against latest release or, better,
against fresh CVS snapshot (downloadable from wxWidgets website).
- cvs diff cannot make a patch which adds or removes a file, so you must use
the standalone diff utility to do that (download from gnu if you don't have
it, e.g. you're using WinCVS). Unlike cvs diff, diff works offline, so you
need both original and modified versions of the wxWidgets directory
hierarchy for diff to compare. Make a copy of your wxWidgets directory (but
please don't name it "Copy of wxWidgets" because it has spaces in it) and use
cvs on it to get the 'clean' copy of any files you've modified and
want to make a patch for - this sets those files back to what's currently
in CVS. Ensure you do a normal update on the development directory (with your
modified files still in it) at the same time, so you don't unintentionally
create a patch which reverts a previous patch. Ensure you run diff with the -N
(or --new-file) option.
- Never edit the patch
on a Windows system with an editor which can't handle/preserve the
Unix like line termination.
- 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.
- 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.
- 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".
- 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 :)
- 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.
- 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.
Thank you for reading this document -- and looking forward to your
patches! :-)
|
|
|