mirror of
https://github.com/reactos/wine.git
synced 2024-12-11 13:26:00 +00:00
235 lines
8.4 KiB
Plaintext
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:
|
|
-->
|