wine/documentation/patches.sgml
Dimitrie O. Paun a713da2fc1 Suggest testing patches in a gentler way.
Encourage people to submit tests with their patches as well.
2005-01-14 15:14:09 +00:00

235 lines
8.4 KiB
Plaintext

<chapter id="patches">
<title>Submitting Patches</title>
<sect1 id="patch-format">
<title>Patch Format</title>
<para>
Patches are submitted via email to the Wine patches mailing list,
<email>wine-patches@winehq.org</email>. Your patch should include:
</para>
<itemizedlist>
<listitem>
<para>
A meaningful subject (very short description of patch)
</para>
</listitem>
<listitem>
<para>
A long (paragraph) description of what was wrong and what is now
better. (recommended)
</para>
</listitem>
<listitem>
<para>
A change log entry (short description of what was changed).
</para>
</listitem>
<listitem>
<para>
The patch in <command>diff -u</command> format
</para>
</listitem>
</itemizedlist>
<para>
</para>
<para>
<command>cvs diff -u</command> works great for the common case
where a file is edited. However, if you add or remove a file
<command>cvs diff</command> will not report that correctly so
make sure you explicitly take care of this rare case.
</para>
<para>
For additions simply include them by appending the
<command>diff -u /dev/null /my/new/file</command> output of them
to any <command>cvs diff -u</command> output you may have.
Alternatively, use <command>diff -Nu olddir/ newdir/</command>
in case of multiple new files to add.
</para>
<para>
For removals, clearly list the files in the description of the patch.
</para>
<para>
Since wine is constantly changing due to development it is strongly
recommended that you use cvs for patches, if you cannot use cvs for
some reason, you can submit patches against the latest tarball.
To do this make a copy of the files that you will be modifying and
<command>diff -u</command> against the old file. I.E.
</para>
<screen>
diff -u file.old file.c > file.txt
</screen>
</sect1>
<sect1 id="Style-notes">
<title>Some notes about style</title>
<para>
There are a few conventions that about coding style that have been
adopted over the years of development. The rational for these
<quote>rules</quote> is explained for each one.
</para>
<itemizedlist>
<listitem>
<para>
No HTML mail, since patches should be in-lined and HTML turns the
patch into garbage. Also it is considered bad etiquette as it
uglifies the message, and is not viewable by many of the subscribers.
</para>
</listitem>
<listitem>
<para>
Only one change set per patch. Patches should address only one
bug/problem at a time. If a lot of changes need to be made then it
is preferred to break it into a series of patches. This makes it
easier to find regressions.
</para>
</listitem>
<listitem>
<para>
Tabs are not forbidden but discouraged. A tab is defined as
8 characters and the usual amount of indentation is 4
characters.
</para>
</listitem>
<listitem>
<para>
C++ style comments are discouraged since some compilers choke on
them.
</para>
</listitem>
<listitem>
<para>
Commenting out a block of code is usually done by enclosing it in
<command>#if 0 ... #endif</command> Statements. For example.
</para>
<screen>
/* note about reason for commenting block */
#if 0
code
code /* comments */
code
#endif
</screen>
<para>
The reason for using this method is that it does not require that
you edit comments that may be inside the block of code.
</para>
</listitem>
<listitem>
<para>
Patches should be in-lined (if you can configure your email client to
not wrap lines), or attached as plain text attachments so they can
be read inline. This may mean some more work for you. However it
allows others to review your patch easily and decreases the chances
of it being overlooked or forgotten.
</para>
</listitem>
<listitem>
<para>
Code is usually limited to 80 columns. This helps prevent mailers
mangling patches by line wrap. Also it generally makes code easier
to read.
</para>
</listitem>
<listitem>
<para>
If the patch fixes a bug in Bugzilla please provide a link to the
bug in the comments of the patch. This will make it easier for the
maintainers of Bugzilla.
</para>
</listitem>
</itemizedlist>
<sect2 id="Inline-Attachments-with-OE">
<title>Inline attachments with Outlook Express</title>
<para>
Outlook Express is notorious for mangling attachments. Giving the
patch a <filename>.txt</filename> extension and attaching will solve
the problem for most mailers including Outlook. Also, there is a way
to enable Outlook Express send <filename>.diff</filename>
attachments.
</para>
<para>
You need following two things to make it work.
</para>
<orderedlist>
<listitem>
<para>
Make sure that <filename>.diff</filename> files have \r\n line
ends, because if OE detects that there is no \r\n line endings it
switches to quoted-printable format attachments.
</para>
</listitem>
<listitem>
<para>
Using regedit add key "Content Type" with value "text/plain"
to the .diff extension under HKEY_CLASSES_ROOT (same as for .txt
extension). This tells OE to use Content-Type: text/plain instead
of application/octet-stream.
</para>
</listitem>
</orderedlist>
<para>
Item #1 is important. After you hit "Send" button, go to "Outbox"
and using "Properties" verify the message source to make sure that
the mail has correct format. You might want to send several test
emails to yourself too.
</para>
</sect2>
<sect2 id="Alexandre-Bottom-Line">
<title>Alexandre's Bottom Line</title>
<para>
<quote>The basic rules are: no attachments, no mime crap, no
line wrapping, a single patch per mail. Basically if I can't
do <command>"cat raw_mail | patch -p0"</command> it's in the
wrong format.</quote>
</para>
</sect2>
</sect1>
<sect1 id="patch-quality">
<title>Quality Assurance</title>
<para>
(Or, "How do I get Alexandre to apply my patch quickly so I
can build on it and it will not go stale?")
</para>
<para>
Make sure your patch applies to the current CVS head
revisions. If a bunch of patches are committed to CVS that may
affect whether your patch will apply cleanly then verify that
your patch does apply! <command>cvs update</command> is your
friend!
</para>
<para>
Try to test your patch against more than just your current test
example. Experience will tell you how much effort to apply here.
If there are any conformance tests for the code you're working on,
run them and make sure they still pass after your patch is applied.
Running tests can be done by running <command>make test</command>.
You may need to run <command>make testclean</command> to undo the
results of a previous test run.
</para>
<para>
Please consider submitting a conformance test for your changes.
This will make it a lot clearer for everyone that your patch is
needed, and it will prevent future breakage. While you are not
strictly required to submit tests, it is highly encouraged to do so.
See the <quote>testing</quote> guide for more details on Wine's
conformance tests.
</para>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")
End:
-->