Update to patches sgml (one more time)

Tony Lambregts tony_lambregts at telusplanet.net
Thu Dec 19 12:57:05 CST 2002


Dimitrie O. Paun wrote:

>On December 19, 2002 01:56 am, Tony Lambregts wrote:
>  
>
>>Not a bad idea. how's this then.
>>    
>>
>
>Better. Did you look at this:
>  http://www.winehq.com/hypermail/wine-devel/2002/09/0127.html
>
>The rules detailed in there are still valid:
>  -- unified diff only (required)
>  -- have a  decent subject (recommended)
>  -- a long description (optional, if the change warrants it)
>  -- a meaningful ChangeLog entry (required)
>  -- new files, if any, included in patch, diffed against /dev/null (required)
>  -- patch inlined at the end of the message (recommended)
>  -- one changeset per message
>
Most of this is covered in the Patch format section  and are in point 
form so I added most of what was missing there.

>
>What about including them in point-form for clarity, with some rationale
>(as you did) for things like patch inlining, etc. Idea being that one
>shouldn't have read the entire story if he/she only wants to see the rules.
>
>The story is good for first timers that want to understand why we have these
>rules/recommendations, so we can easily point them to them instead of having
>to answer it in long email every time... :)
>
>  
>
The whole thing isn't much more that a couple hundred words and in point 
form.  I think most developrers are capable of getting the idea without 
having to go back to it each time they send a patch <g>

Change Log: update patches.sgml to include more information on style and 
format of patches

Files: documentation/patches.sgml

-- 

Tony Lambregts


-------------- next part --------------
Index: patches.sgml
===================================================================
RCS file: /home/wine/wine/documentation/patches.sgml,v
retrieving revision 1.4
diff -u -r1.4 patches.sgml
--- patches.sgml	17 Sep 2002 00:07:03 -0000	1.4
+++ patches.sgml	19 Dec 2002 18:36:29 -0000
@@ -14,18 +14,28 @@
       <itemizedlist>
         <listitem>
           <para>
-            a description of what was wrong and what is now better
-            (and now broken :).
+            A meaningfull 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 :). (recomended)
+          </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 )
+            Your contact information ( Name/Handle and e-mail )
           </para>
         </listitem>
         <listitem>
           <para>
-            the patch in <command>diff -u</command> format (it happens...)
+            The patch in <command>diff -u</command> format (it happens...)
           </para>
         </listitem>
       </itemizedlist>
@@ -47,6 +57,82 @@
       <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>
+           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 are defined as 8 charaters 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>
     </sect1>
 
     <sect1 id="patch-quality">


More information about the wine-patches mailing list