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 description of what was wrong and what is now better
  18             (and now broken :).
  19           </para>
  20         </listitem>
  21         <listitem>
  22           <para>
  23             your contact information ( Name/Handle and e-mail )
  24           </para>
  25         </listitem>
  26         <listitem>
  27           <para>
  28             the patch in <command>diff -u</command> format (it happens...)
  29           </para>
  30         </listitem>
  31       </itemizedlist>
  32
  33       <para>
  34         <command>cvs diff -u</command> works great for the common case
  35         where a file is edited.  However, if you add or remove a file
  36         <command>cvs diff</command> will not report that correctly so
  37         make sure you explicitly take care of this rare case.
  38       </para>
  39       <para>
  40         For additions: mention that you have some new files and
  41         include them as either separate attachments or by appending
  42         the <command>diff -u /dev/null /my/new/file</command> output of them
  43         to any <command>cvs diff -u</command> output you may have.
  44         Alternatively, use <command>diff -Nu olddir/ newdir/</command>
  45         in case of multiple new files to add.
  46       </para>
  47       <para>
  48         For removals, list the files.
  49       </para>
  50     </sect1>
  51
  52     <sect1 id="patch-quality">
  53       <title>Quality Assurance</title>
  54
  55       <para>
  56         (Or, "How do I get Alexandre to apply my patch quickly so I
  57         can build on it and it will not go stale?")
  58       </para>
  59       <para>
  60         Make sure your patch applies to the current CVS head
  61         revisions.  If a bunch of patches are commited to CVS that may
  62         affect whether your patch will apply cleanly then verify that
  63         your patch does apply!   <command>cvs update</command> is your
  64         friend!
  65       </para>
  66       <para>
  67         Save yourself some embarasment and run your patched code
  68         against more than just your current test example.  Experience
  69         will tell you how much effort to apply here.
  70       </para>
  71
  72     </sect1>
  73   </chapter>
  74
  75 <!-- Keep this comment at the end of the file
  76 Local variables:
  77 mode: sgml
  78 sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
  79 End:
  80 -->