From 18a79c8b69d18a2fec800a4ecfa9bc53bbb583f6 Mon Sep 17 00:00:00 2001 From: Tony Lambregts Date: Thu, 19 Dec 2002 23:43:46 +0000 Subject: [PATCH] More information on style and format of patches. --- documentation/patches.sgml | 130 +++++++++++++++++++++++++++++++++++-- 1 file changed, 126 insertions(+), 4 deletions(-) diff --git a/documentation/patches.sgml b/documentation/patches.sgml index 2c6fa7a6132..6b5a6c6cef0 100644 --- a/documentation/patches.sgml +++ b/documentation/patches.sgml @@ -14,18 +14,28 @@ - a description of what was wrong and what is now better - (and now broken :). + A meaningfull subject (very short description of patch) + + + + + A long (paragraph) description of what was wrong and what is now + better (and now broken :). (recomended) - your contact information ( Name/Handle and e-mail ) + Change Log: A short description of what was changed. - the patch in diff -u format (it happens...) + Your contact information ( Name/Handle and e-mail ) + + + + + The patch in diff -u format (it happens...) @@ -47,6 +57,118 @@ For removals, list the files. + + 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 + diff -u against the old file. I.E. + + +diff -u file.old file.c > file.txt + + + + + Some notes about style + + + There are a few conventions that about coding style that have been + adopted over the years of development. The rational for these + rules is explained for each one. + + + + + 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. + + + + + Tabs are not forbidden but are defined as 8 charaters and the usual + amount of indentation is 4 characters. + + + + + C++ style comments are discouraged since some compilers choke on + them. + + + + + Commenting out a block of code is usually done by enclosing it in + #if 0 ... #endif Statements. For example. + + +/* note about reason for commenting block */ +#if 0 +code +code /* comments */ +code +#endif + + + The reason for using this method is that it does not require that + you edit comments that may be inside the block of code. + + + + + 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. + + + + + Code is usually limited to 80 columns. This helps prevent mailers + mangling patches by line wrap. Also it generally makes code easier + to read. + + + + + Inline attachments with Outlook Express + + Outlook Express is notorious for mangleing attachements. Giving the + patch a .txt extention and attaching will solve + the problem for most mailers including Outlook. Also, there is a way + to enable Outlook Express send .diff + attachmnets. + + + You need following two things to make it work. + + + + + Make sure that .diff files have \r\n line + ends, because if OE detects that there is no \r\n line endings it + switches to quoted-printable format attachments. + + + + + Using regedit add key "Content Type" with value "text/plain" + to the .diff extension under HKEY_CLASSES_ROOT (same as for .txt + extension). This tells OE to use Content-Type: text/plain instead + of application/octet-stream. + + + + + Item #1 is important. After you hit "Send" button, go to "Outbox" + and using "Properties" verify the message source to make sure that + the mail has correct format. You might want to send several test + emails to yourself too. + +