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
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">
