documentation/patches.sgml

   1   <chapter id="patches">
   2     <title>Submitting Patches</title>
   3
   4     <para>
   5       Written by &name-albert-den-haan; <email>&email-albert-den-haan;</email>
   6     </para>
   7     <sect1 id="patch-format">
   8       <title>Patch Format</title>
   9
  10       <para>
  11         Your patch should include:
  12       </para>
  13
  14       <itemizedlist>
  15         <listitem>
  16           <para>
  17             A meaningful subject (very short description of patch)
  18           </para>
  19         </listitem>
  20          <listitem>
  21           <para>
  22             A long (paragraph) description of what was wrong and what is now
  23             better (and now broken :). (recommended)
  24           </para>
  25         </listitem>
  26         <listitem>
  27           <para>
  28             Change Log: A short description of what was changed.
  29           </para>
  30         </listitem>
  31         <listitem>
  32           <para>
  33             Your contact information ( Name/Handle and e-mail )
  34           </para>
  35         </listitem>
  36         <listitem>
  37           <para>
  38             The patch in <command>diff -u</command> format (it happens...)
  39           </para>
  40         </listitem>
  41       </itemizedlist>
  42
  43       <para>
  44         <command>cvs diff -u</command> works great for the common case
  45         where a file is edited.  However, if you add or remove a file
  46         <command>cvs diff</command> will not report that correctly so
  47         make sure you explicitly take care of this rare case.
  48       </para>
  49       <para>
  50         For additions: mention that you have some new files and
  51         include them by appending the
  52         <command>diff -u /dev/null /my/new/file</command> output of them
  53         to any <command>cvs diff -u</command> output you may have.
  54         Alternatively, use <command>diff -Nu olddir/ newdir/</command>
  55         in case of multiple new files to add.
  56       </para>
  57       <para>
  58         For removals, list the files.
  59       </para>
  60       <para>
  61         Since wine is constantly changing due to development it is strongly
  62         recommended that you use cvs for patches, if you cannot use cvs for
  63         some reason, you can submit patches against the latest tarball.
  64         To do this make a copy of the files that you will be modifying and
  65         <command>diff -u</command> against the old file. I.E.
  66       </para>
  67       <screen>
  68 diff -u file.old file.c > file.txt
  69       </screen>
  70     </sect1>
  71
  72     <sect1 id="Style-notes">
  73       <title>Some notes about style</title>
  74
  75       <para>
  76         There are a few conventions that about coding style that have been
  77         adopted over the years of development. The rational for these
  78         <quote>rules</quote> is explained for each one.
  79       </para>
  80       <itemizedlist>
  81         <listitem>
  82         <para>
  83           No HTML mail, since patches should be in-lined and HTML turns the
  84           patch into garbage. Also it is considered bad etiquette as it
  85           uglifies the message, and is not viewable by many of the subscribers.
  86         </para>
  87         </listitem>
  88          <listitem>
  89         <para>
  90            Only one change set per patch. Patches should address only one
  91            bug/problem at a time. If a lot of changes need to be made then it
  92            is preferred to break it into a series of patches. This makes it
  93            easier to find regressions.
  94         </para>
  95         </listitem>
  96         <listitem>
  97         <para>
  98           Tabs are not forbidden but discouraged. A tab is defined as
  99           8 characters and the usual amount of indentation is 4
 100           characters.
 101         </para>
 102         </listitem>
 103         <listitem>
 104         <para>
 105           C++ style comments are discouraged since some compilers choke on
 106           them.
 107         </para>
 108         </listitem>
 109         <listitem>
 110         <para>
 111           Commenting out a block of code is usually done by enclosing it in
 112           <command>#if 0 ... #endif</command> Statements. For example.
 113         </para>
 114         <screen>
 115 /* note about reason for commenting block */
 116 #if 0
 117 code
 118 code /* comments */
 119 code
 120 #endif
 121         </screen>
 122         <para>
 123           The reason for using this method is that it does not require that
 124           you edit comments that may be inside the block of code.
 125         </para>
 126         </listitem>
 127         <listitem>
 128         <para>
 129           Patches should be in-lined (if you can configure your email client to
 130           not wrap lines), or attached as plain text attachments so they can
 131           be read inline. This may mean some more work for you. However it
 132           allows others to review your patch easily and decreases the chances
 133           of it being overlooked or forgotten.
 134         </para>
 135         </listitem>
 136         <listitem>
 137         <para>
 138           Code is usually limited to 80 columns. This helps prevent mailers
 139           mangling patches by line wrap. Also it generally makes code easier
 140           to read.
 141         </para>
 142         </listitem>
 143       </itemizedlist>
 144       <sect2 id="Inline-Attachments-with-OE">
 145         <title>Inline attachments with Outlook Express</title>
 146         <para>
 147           Outlook Express is notorious for mangling attachments. Giving the
 148           patch a <filename>.txt</filename> extension and attaching will solve
 149           the problem for most mailers including Outlook. Also, there is a way
 150           to enable Outlook Express send <filename>.diff</filename>
 151           attachments.
 152         </para>
 153         <para>
 154           You need following two things to make it work.
 155         </para>
 156         <orderedlist>
 157           <listitem>
 158           <para>
 159             Make sure that <filename>.diff</filename> files have \r\n line
 160             ends, because if OE detects that there is no \r\n line endings it
 161             switches to quoted-printable format attachments.
 162           </para>
 163           </listitem>
 164           <listitem>
 165           <para>
 166             Using regedit add key "Content Type" with value "text/plain"
 167             to the .diff extension under HKEY_CLASSES_ROOT (same as for .txt
 168             extension). This tells OE to use Content-Type: text/plain instead
 169             of application/octet-stream.
 170           </para>
 171           </listitem>
 172         </orderedlist>
 173         <para>
 174           Item #1 is important. After you hit "Send" button, go to "Outbox"
 175           and using "Properties" verify the message source to make sure that
 176           the mail has correct format. You might want to send several test
 177           emails to yourself too.
 178         </para>
 179       </sect2>
 180       <sect2 id="Alexandre-Bottom-Line">
 181         <title>Alexandre's Bottom Line</title>
 182         <para>
 183           <quote>The basic rules are: no attachments, no mime crap, no
 184           line wrapping, a single patch per mail. Basically if I can't
 185           do <Command>"cat raw_mail | patch -p0"</command> it's in the
 186           wrong format.</quote>
 187         </para>
 188       </sect2>
 189     </sect1>
 190
 191     <sect1 id="patch-quality">
 192       <title>Quality Assurance</title>
 193
 194       <para>
 195         (Or, "How do I get Alexandre to apply my patch quickly so I
 196         can build on it and it will not go stale?")
 197       </para>
 198       <para>
 199         Make sure your patch applies to the current CVS head
 200         revisions.  If a bunch of patches are committed to CVS that may
 201         affect whether your patch will apply cleanly then verify that
 202         your patch does apply!   <command>cvs update</command> is your
 203         friend!
 204       </para>
 205       <para>
 206         Save yourself some embarrassment and run your patched code
 207         against more than just your current test example.  Experience
 208         will tell you how much effort to apply here.
 209       </para>
 210
 211     </sect1>
 212   </chapter>
 213
 214 <!-- Keep this comment at the end of the file
 215 Local variables:
 216 mode: sgml
 217 sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")
 218 End:
 219 -->