2 <title>Submitting Patches</title>
5 Written by &name-albert-den-haan; <email>&email-albert-den-haan;</email>
7 <sect1 id="patch-format">
8 <title>Patch Format</title>
11 Your patch should include:
17 A meaningfull subject (very short description of patch)
22 A long (paragraph) description of what was wrong and what is now
23 better (and now broken :). (recomended)
28 Change Log: A short description of what was changed.
33 Your contact information ( Name/Handle and e-mail )
38 The patch in <command>diff -u</command> format (it happens...)
44 <command>cvs diff -u</command> works great for the common case
45 where a file is edited. However, if you add or remove a file
46 <command>cvs diff</command> will not report that correctly so
47 make sure you explicitly take care of this rare case.
50 For additions: mention that you have some new files and
51 include them as either separate attachments or by appending
52 the <command>diff -u /dev/null /my/new/file</command> output of them
53 to any <command>cvs diff -u</command> output you may have.
54 Alternatively, use <command>diff -Nu olddir/ newdir/</command>
55 in case of multiple new files to add.
58 For removals, list the files.
61 Since wine is constantly changing due to development it is strongly
62 recomended that you use cvs for patches, if you cannot use cvs for
63 some reason, you can submit patches against the latest tarball.
64 To do this make a copy of the files that you will be modifying and
65 <command>diff -u</command> against the old file. I.E.
68 diff -u file.old file.c > file.txt
72 <sect1 id="Style-notes">
73 <title>Some notes about style</title>
76 There are a few conventions that about coding style that have been
77 adopted over the years of development. The rational for these
78 <quote>rules</quote> is explained for each one.
83 Only one change set per patch. Patches should address only one
84 bug/problem at a time. If a lot of changes need to be made then it
85 is perfered to break it into a series of patches. This makes it
86 easier to find regressions.
91 Tabs are not forbidden but are defined as 8 charaters and the usual
92 amount of indentation is 4 characters.
97 C++ style comments are discouraged since some compilers choke on
103 Commenting out a block of code is usually done by enclosing it in
104 <command>#if 0 ... #endif</command> Statements. For example.
107 /* note about reason for commenting block */
115 The reason for using this method is that it does not require that
116 you edit comments that may be inside the block of code.
121 Patches should be inlined (if you can configure your email client to
122 not wrap lines), or attached as plain text attachements so they can
123 be read inline. This may mean some more work for you. However it
124 allows others to review your patch easily and decreases the chances
125 of it being overlooked or forgotten.
130 Code is usually limited to 80 columns. This helps prevent mailers
131 mangling patches by line wrap. Also it generally makes code easier
136 <sect2 id="Inline-Attachments-with-OE">
137 <title>Inline attachments with Outlook Express</title>
139 Outlook Express is notorious for mangleing attachements. Giving the
140 patch a <filename>.txt</filename> extention and attaching will solve
141 the problem for most mailers including Outlook. Also, there is a way
142 to enable Outlook Express send <filename>.diff</filename>
146 You need following two things to make it work.
151 Make sure that <filename>.diff</filename> files have \r\n line
152 ends, because if OE detects that there is no \r\n line endings it
153 switches to quoted-printable format attachments.
158 Using regedit add key "Content Type" with value "text/plain"
159 to the .diff extension under HKEY_CLASSES_ROOT (same as for .txt
160 extension). This tells OE to use Content-Type: text/plain instead
161 of application/octet-stream.
166 Item #1 is important. After you hit "Send" button, go to "Outbox"
167 and using "Properties" verify the message source to make sure that
168 the mail has correct format. You might want to send several test
169 emails to yourself too.
174 <sect1 id="patch-quality">
175 <title>Quality Assurance</title>
178 (Or, "How do I get Alexandre to apply my patch quickly so I
179 can build on it and it will not go stale?")
182 Make sure your patch applies to the current CVS head
183 revisions. If a bunch of patches are commited to CVS that may
184 affect whether your patch will apply cleanly then verify that
185 your patch does apply! <command>cvs update</command> is your
189 Save yourself some embarasment and run your patched code
190 against more than just your current test example. Experience
191 will tell you how much effort to apply here.
197 <!-- Keep this comment at the end of the file
200 sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")