documentation/patches.sgml

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