This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
support USE_THREADS+MULTIPLICITY; source compat tweaks for
[perl5.git] / Porting / patching.pod
1 =head1 Name
2
3 patching.pod - Appropriate format for patches to the perl source tree
4
5 =head2 Where to get this document
6
7 The latest version of this document is available from
8      http://perrin.dimensional.com/perl/perlpatch.html
9
10 =head2 How to contribute to this document
11
12 You may mail corrections, additions, and suggestions to me
13 at dgris@dimensional.com but the preferred method would be
14 to follow the instructions set forth in this document and 
15 submit a patch 8-).
16
17 =head1 Description
18
19 =head2 Why this document exists
20
21 As an open source project Perl relies on patches and contributions from
22 its users to continue functioning properly and to root out the inevitable
23 bugs.  But, some users are unsure as to the I<right> way to prepare a patch
24 and end up submitting seriously malformed patches.  This makes it very
25 difficult for the current maintainer to integrate said patches into their
26 distribution.  This document sets out usage guidelines for patches in an
27 attempt to make everybody's life easier.
28
29 =head2 Common problems
30
31 The most common problems appear to be patches being mangled by certain
32 mailers (I won't name names, but most of these seem to be originating on
33 boxes running a certain popular commercial operating system).  Other problems
34 include patches not rooted in the appropriate place in the directory structure,
35 and patches not produced using standard utilities (such as diff).
36
37 =head1 Proper Patch Guidelines
38
39 =head2 What to patch
40
41 Generally speaking you should patch the latest development release
42 of perl.  The maintainers of the individual branches will see to it
43 that patches are picked up and applied as appropriate.
44
45 =head2 How to prepare your patch
46
47 =over 4
48
49 =item Creating your patch
50
51 First, back up the original files.  This can't be stressed enough,
52 back everything up _first_.
53
54 Also, please create patches against a clean distribution of the perl source.
55 This ensures that everyone else can apply your patch without clobbering their
56 source tree.
57
58 =item diff
59
60 While individual tastes vary (and are not the point here) patches should
61 be created using either C<-u> or C<-c> arguments to diff.  These produce,
62 respectively, unified diffs (where the changed line appears immediately next
63 to the original) and context diffs (where several lines surrounding the changes
64 are included).  See the manpage for diff for more details.
65
66 The preferred method for creating a unified diff suitable for feeding
67 to the patch program is:
68
69         diff -u old-file new-file > patch-file
70
71 Note the order of files.  See below for how to create a patch from
72 two directory trees.
73
74 If your patch is for wider consumption, it may be better to create it as
75 a context diff as some machines have broken patch utilities that choke on
76 unified diffs.  A context diff is made using C<diff -c> rather than
77 C<diff -u>.
78
79 GNU diff has many desirable features not provided by most vendor-supplied
80 diffs.  Some examples using GNU diff:
81
82     # generate a patch for a newly added file
83     % diff -u /dev/null new/file
84     
85     # generate a patch to remove a file (patch > v2.4 will remove it cleanly)
86     % diff -u old/goner /dev/null
87     
88     # get additions, deletions along with everything else, recursively
89     % diff -ruN olddir newdir
90     
91     # ignore whitespace
92     % diff -bu a/file b/file
93     
94     # show function name in every hunk (safer, more informative)
95     % diff -u -F '^[_a-zA-Z0-9]+ *(' old/file new/file
96
97
98 =item Directories
99
100 IMPORTANT: Patches should be generated from the source root directory, not
101 from the directory that the patched file resides in.  This ensures that the
102 maintainer patches the proper file.
103
104 Many files in the distribution are derivative--avoid patching them.
105 Patch the originals instead.  Most utilities (like perldoc) are in
106 this category, i.e. patch utils/perldoc.PL rather than utils/perldoc.
107 Similarly, don't create patches for files under $src_root/ext from
108 their copies found in $install_root/lib.  If you are unsure about the
109 proper location of a file that may have gotten copied while building
110 the source distribution, consult the C<MANIFEST>.
111
112 =item Filenames
113
114 The most usual convention when submitting patches for a single file is to make
115 your changes to a copy of the file with the same name as the original.  Rename
116 the original file in such a way that it is obvious what is being patched
117 ($file.dist or $file.old seem to be popular).
118
119 If you are submitting patches that affect multiple files then you should
120 backup the entire directory tree (to $source_root.old/ for example).  This
121 will allow C<diff -ruN old-dir new-dir> to create all the patches at once.
122
123 =item Try it yourself
124
125 Just to make sure your patch "works", be sure to apply it to the Perl
126 distribution, rebuild everything, and make sure the testsuite runs
127 without incident.
128
129 =back
130
131 =head2 What to include in your patch
132
133 =over 4
134
135 =item Description of problem
136
137 The first thing you should include is a description of the problem that
138 the patch corrects.  If it is a code patch (rather than a documentation
139 patch) you should also include a small test case that illustrates the
140 bug.
141
142 =item Directions for application
143
144 You should include instructions on how to properly apply your patch.
145 These should include the files affected, any shell scripts or commands
146 that need to be run before or after application of the patch, and
147 the command line necessary for application.
148
149 =item If you have a code patch
150
151 If you are submitting a code patch there are several other things that
152 you need to do.
153
154 =over 4
155
156 =item Comments, Comments, Comments
157
158 Be sure to adequately comment your code.  While commenting every
159 line is unnecessary, anything that takes advantage of side effects of
160 operators, that creates changes that will be felt outside of the
161 function being patched, or that others may find confusing should
162 be documented.  If you are going to err, it is better to err on the
163 side of adding too many comments than too few.
164
165 =item Style
166
167 In general, please follow the particular style of the code you are patching.
168
169 In particular, follow these general guidelines for patching Perl sources:
170
171     8-wide tabs (no exceptions!)
172     4-wide indents for code, 2-wide indents for nested CPP #defines
173     try hard not to exceed 79-columns
174     ANSI C prototypes
175     uncuddled elses and "K&R" style for indenting control constructs
176     no C++ style (//) comments, most C compilers will choke on them
177     mark places that need to be revisited with XXX (and revisit often!)
178     opening brace lines up with "if" when conditional spans multiple
179         lines; should be at end-of-line otherwise
180     in function definitions, name starts in column 0 (return value is on
181         previous line)
182     single space after keywords that are followed by parens, no space
183         between function name and following paren
184     avoid assignments in conditionals, but if they're unavoidable, use
185         extra paren, e.g. "if (a && (b = c)) ..."
186     "return foo;" rather than "return(foo);"
187     "if (!foo) ..." rather than "if (foo == FALSE) ..." etc.
188
189
190 =item Testsuite
191
192 When submitting a patch you should make every effort to also include
193 an addition to perl's regression tests to properly exercise your
194 patch.  Your testsuite additions should generally follow these
195 guidelines (courtesy of Gurusamy Sarathy <gsar@activestate.com>):
196
197         Know what you're testing.  Read the docs, and the source.
198         Tend to fail, not succeed.
199         Interpret results strictly.
200         Use unrelated features (this will flush out bizarre interactions).
201         Use non-standard idioms (otherwise you are not testing TIMTOWTDI).
202         Avoid using hardcoded test numbers whenever possible (the 
203           EXPECTED/GOT found in t/op/tie.t is much more maintainable, 
204           and gives better failure reports).
205         Give meaningful error messages when a test fails.
206         Avoid using qx// and system() unless you are testing for them.  If you
207           do use them, make sure that you cover _all_ perl platforms.
208         Unlink any temporary files you create.
209         Promote unforeseen warnings to errors with $SIG{__WARN__}.
210         Be sure to use the libraries and modules shipped with the version 
211           being tested, not those that were already installed.
212         Add comments to the code explaining what you are testing for.
213         Make updating the '1..42' string unnecessary.  Or make sure that 
214           you update it.
215         Test _all_ behaviors of a given operator, library, or function:
216           - All optional arguments
217           - Return values in various contexts (boolean, scalar, list, lvalue)
218           - Use both global and lexical variables
219           - Don't forget the exceptional, pathological cases.
220
221 =back
222
223 =item Test your patch
224
225 Apply your patch to a clean distribution, compile, and run the
226 regression test suite (you did remember to add one for your
227 patch, didn't you).
228
229 =back
230
231 =head2 An example patch creation
232
233 This should work for most patches:
234
235       cp MANIFEST MANIFEST.old
236       emacs MANIFEST
237       (make changes)
238       cd ..
239       diff -c perl5.008_42/MANIFEST.old perl5.008_42/MANIFEST > mypatch
240       (testing the patch:)
241       mv perl5.008_42/MANIFEST perl5.008_42/MANIFEST.new
242       cp perl5.008_42/MANIFEST.old perl5.008_42/MANIFEST
243       patch -p < mypatch
244       (should succeed)
245       diff perl5.008_42/MANIFEST perl5.008_42/MANIFEST.new
246       (should produce no output)
247
248 =head2 Submitting your patch
249
250 =over 4
251
252 =item Mailers
253
254 Please, please, please (get the point? 8-) don't use a mailer that
255 word wraps your patch or that MIME encodes it.  Both of these leave
256 the patch essentially worthless to the maintainer.
257
258 If you have no choice in mailers and no way to get your hands on a
259 better one there is, of course, a perl solution.  Just do this:
260
261       perl -ne 'print pack("u*",$_)' patch > patch.uue
262
263 and post patch.uue with a note saying to unpack it using
264
265       perl -ne 'print unpack("u*",$_)' patch.uue > patch
266
267 =item Subject lines for patches
268
269 The subject line on your patch should read
270
271     [PATCH 5.xxx_xx AREA] Description
272
273 where the x's are replaced by the appropriate version number.
274 The description should be a very brief but accurate summary of the
275 problem (don't forget this is an email header).
276
277 Examples:
278
279     [PATCH 5.004_04 DOC] fix minor typos
280
281     [PATCH 5.004_99 CORE] New warning for foo() when frobbing
282
283     [PATCH 5.005_42 CONFIG] Added support for fribnatz 1.5
284
285 The name of the file being patched makes for a poor subject line if
286 no other descriptive text accompanies it.
287
288 =item Where to send your patch
289
290 If your patch is for a specific bug in the Perl core, it should be sent
291 using the perlbug utility.  Don't forget to describe the problem and the
292 fix adequately.
293
294 If it is a patch to a module that you downloaded from CPAN you should
295 submit your patch to that module's author.
296
297 If your patch addresses one of the items described in perltodo.pod,
298 please discuss your approach B<before> you make the patch at
299 <perl5-porters@perl.org>.  Be sure to browse the archives of past
300 discussions (see perltodo.pod for archive locations).
301
302 =back
303
304 =head2 Applying a patch
305
306 =over 4
307
308 =item General notes on applying patches
309
310 The following are some general notes on applying a patch
311 to your perl distribution.
312
313 =over 4
314
315 =item patch C<-p>
316
317 It is generally easier to apply patches with the C<-p N> argument to
318 patch (where N is the number of path components to skip in the files
319 found in the headers).  This helps reconcile differing paths between
320 the machine the patch was created on and the machine on which it is
321 being applied.
322
323 =item Cut and paste
324
325 B<Never> cut and paste a patch into your editor.  This usually clobbers
326 the tabs and confuses patch.
327
328 =item Hand editing patches
329
330 Avoid hand editing patches as this almost always screws up the line
331 numbers and offsets in the patch, making it useless.
332
333 =back
334
335 =back
336
337 =head2 Final notes
338
339 If you follow these guidelines it will make everybody's life a little
340 easier.  You'll have the satisfaction of having contributed to perl,
341 others will have an easy time using your work, and it should be easier
342 for the maintainers to coordinate the occasionally large numbers of 
343 patches received.
344
345 Also, just because you're not a brilliant coder doesn't mean that you
346 can't contribute.  As valuable as code patches are there is always a
347 need for better documentation (especially considering the general
348 level of joy that most programmers feel when forced to sit down and
349 write docs).  If all you do is patch the documentation you have still
350 contributed more than the person who sent in an amazing new feature
351 that no one can use because no one understands the code (what I'm
352 getting at is that documentation is both the hardest part to do
353 (because everyone hates doing it) and the most valuable).
354
355 Mostly, when contributing patches, imagine that it is B<you> receiving
356 hundreds of patches and that it is B<your> responsibility to integrate
357 them into the source.  Obviously you'd want the patches to be as easy
358 to apply as possible.  Keep that in mind.  8-)
359
360 =head1 Last Modified
361
362 Last modified 21 January 1999 
363 Daniel Grisinger <dgris@dimensional.com>
364
365 =head1 Author and Copyright Information
366
367 Copyright (c) 1998 Daniel Grisinger
368
369 Adapted from a posting to perl5-porters by Tim Bunce (Tim.Bunce@ig.co.uk).
370
371 I'd like to thank the perl5-porters for their suggestions.