220 lines
7.6 KiB
Plaintext
220 lines
7.6 KiB
Plaintext
<chapter id="patches">
|
|
<title>Submitting Patches</title>
|
|
|
|
<para>
|
|
Written by &name-albert-den-haan; <email>&email-albert-den-haan;</email>
|
|
</para>
|
|
<sect1 id="patch-format">
|
|
<title>Patch Format</title>
|
|
|
|
<para>
|
|
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 (and now broken :). (recommended)
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Change Log: A short description of what was changed.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Your contact information ( Name/Handle and e-mail )
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The patch in <command>diff -u</command> format (it happens...)
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<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: mention that you have some new files and
|
|
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, list the files.
|
|
</para>
|
|
<para>
|
|
Since wine is constantly changing due to development it is strongly
|
|
recomended 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 inlined and HTML turns the
|
|
patch into garbage. Also it is considered bad netiquette 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 perfered 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 inlined (if you can configure your email client to
|
|
not wrap lines), or attached as plain text attachements 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>
|
|
</itemizedlist>
|
|
<sect2 id="Inline-Attachments-with-OE">
|
|
<title>Inline attachments with Outlook Express</title>
|
|
<para>
|
|
Outlook Express is notorious for mangleing attachements. Giving the
|
|
patch a <filename>.txt</filename> extention and attaching will solve
|
|
the problem for most mailers including Outlook. Also, there is a way
|
|
to enable Outlook Express send <filename>.diff</filename>
|
|
attachmnets.
|
|
</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 commited 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>
|
|
Save yourself some embarrassment and run your patched code
|
|
against more than just your current test example. Experience
|
|
will tell you how much effort to apply here.
|
|
</para>
|
|
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
|
|
End:
|
|
-->
|