Mac OS X: tweak once again the installation directories.
[p5sagit/p5-mst-13.2.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 When GNU diff is available, the pumpkins would prefer you use C<-u -p>
67 (--unified --show-c-function) as arguments for optimal control. The
68 examples below will only use -u.
69
70 The preferred method for creating a unified diff suitable for feeding
71 to the patch program is:
72
73         diff -u old-file new-file > patch-file
74
75 Note the order of files.  See below for how to create a patch from
76 two directory trees.
77
78 If your patch is for wider consumption, it may be better to create it as
79 a context diff as some machines have broken patch utilities that choke on
80 unified diffs.  A context diff is made using C<diff -c> rather than
81 C<diff -u>.
82
83 GNU diff has many desirable features not provided by most vendor-supplied
84 diffs.  Some examples using GNU diff:
85
86     # generate a patch for a newly added file
87     % diff -u /dev/null new/file
88     
89     # generate a patch to remove a file (patch > v2.4 will remove it cleanly)
90     % diff -u old/goner /dev/null
91     
92     # get additions, deletions along with everything else, recursively
93     % diff -ruN olddir newdir
94     
95     # ignore whitespace
96     % diff -bu a/file b/file
97     
98     # show function name in every hunk (safer, more informative)
99     % diff -u -p old/file new/file
100     % diff -u -F '^[_a-zA-Z0-9]+ *(' old/file new/file
101
102     # show sub name in perl files and modules
103     % diff -u -F '^sub' old/file.pm new/file.pm
104
105     # show header in doc patches
106     % diff -u -F '^=head' old/file.pod new/file.pod
107
108 =item Derived Files
109
110 Many files in the distribution are derivative--avoid patching them.
111 Patch the originals instead.  Most utilities (like perldoc) are in
112 this category, i.e. patch utils/perldoc.PL rather than utils/perldoc.
113 Similarly, don't create patches for files under $src_root/ext from
114 their copies found in $install_root/lib.  If you are unsure about the
115 proper location of a file that may have gotten copied while building
116 the source distribution, consult the C<MANIFEST>.
117
118 =item Filenames
119
120 The most usual convention when submitting patches for a single file is to make
121 your changes to a copy of the file with the same name as the original.  Rename
122 the original file in such a way that it is obvious what is being patched
123 ($file.dist or $file.old seem to be popular).
124
125 If you are submitting patches that affect multiple files then you should
126 backup the entire directory tree (to $source_root.old/ for example).  This
127 will allow C<diff -ruN old-dir new-dir> to create all the patches at once.
128
129 =item Directories
130
131 IMPORTANT: Patches should be generated from the source root directory, not
132 from the directory that the patched file resides in.  This ensures that the
133 maintainer patches the proper file.
134
135 For larger patches that are dealing with multiple files or
136 directories, Johan Vromans has written a powerful utility: makepatch.
137 See the JV directory on CPAN for the current version. If you have this
138 program available, it is recommended to create a duplicate of the perl
139 directory tree against which you are intending to provide a patch and
140 let makepatch figure out all the changes you made to your copy of the
141 sources. As perl comes with a MANIFEST file, you need not delete
142 object files and other derivative files from the two directory trees,
143 makepatch is smart about them.
144
145 Say, you have created a directory perl-5.7.1@8685/ for the perl you
146 are taking as the base and a directory perl-5.7.1@8685-withfoo/ where
147 you have your changes, you would run makepatch as follows:
148
149     makepatch -oldman perl-5.7.1@8685/MANIFEST \
150               -newman perl-5.7.1@8685-withfoo/MANIFEST \
151               -diff "diff -u" \
152               perl-5.7.1@8685 perl-5.7.1@8685-withfoo
153
154 =item Try it yourself
155
156 Just to make sure your patch "works", be sure to apply it to the Perl
157 distribution, rebuild everything, and make sure the testsuite runs
158 without incident.
159
160 =back
161
162 =head2 What to include in your patch
163
164 =over 4
165
166 =item Description of problem
167
168 The first thing you should include is a description of the problem that
169 the patch corrects.  If it is a code patch (rather than a documentation
170 patch) you should also include a small test case that illustrates the
171 bug.
172
173 =item Directions for application
174
175 You should include instructions on how to properly apply your patch.
176 These should include the files affected, any shell scripts or commands
177 that need to be run before or after application of the patch, and
178 the command line necessary for application.
179
180 =item If you have a code patch
181
182 If you are submitting a code patch there are several other things that
183 you need to do.
184
185 =over 4
186
187 =item Comments, Comments, Comments
188
189 Be sure to adequately comment your code.  While commenting every
190 line is unnecessary, anything that takes advantage of side effects of
191 operators, that creates changes that will be felt outside of the
192 function being patched, or that others may find confusing should
193 be documented.  If you are going to err, it is better to err on the
194 side of adding too many comments than too few.
195
196 =item Style
197
198 In general, please follow the particular style of the code you are patching.
199
200 In particular, follow these general guidelines for patching Perl sources:
201
202     8-wide tabs (no exceptions!)
203     4-wide indents for code, 2-wide indents for nested CPP #defines
204     try hard not to exceed 79-columns
205     ANSI C prototypes
206     uncuddled elses and "K&R" style for indenting control constructs
207     no C++ style (//) comments, most C compilers will choke on them
208     mark places that need to be revisited with XXX (and revisit often!)
209     opening brace lines up with "if" when conditional spans multiple
210         lines; should be at end-of-line otherwise
211     in function definitions, name starts in column 0 (return value is on
212         previous line)
213     single space after keywords that are followed by parens, no space
214         between function name and following paren
215     avoid assignments in conditionals, but if they're unavoidable, use
216         extra paren, e.g. "if (a && (b = c)) ..."
217     "return foo;" rather than "return(foo);"
218     "if (!foo) ..." rather than "if (foo == FALSE) ..." etc.
219
220
221 =item Testsuite
222
223 When submitting a patch you should make every effort to also include
224 an addition to perl's regression tests to properly exercise your
225 patch.  Your testsuite additions should generally follow these
226 guidelines (courtesy of Gurusamy Sarathy <gsar@activestate.com>):
227
228         Know what you're testing.  Read the docs, and the source.
229         Tend to fail, not succeed.
230         Interpret results strictly.
231         Use unrelated features (this will flush out bizarre interactions).
232         Use non-standard idioms (otherwise you are not testing TIMTOWTDI).
233         Avoid using hardcoded test numbers whenever possible (the 
234           EXPECTED/GOT found in t/op/tie.t is much more maintainable, 
235           and gives better failure reports).
236         Give meaningful error messages when a test fails.
237         Avoid using qx// and system() unless you are testing for them.  If you
238           do use them, make sure that you cover _all_ perl platforms.
239         Unlink any temporary files you create.
240         Promote unforeseen warnings to errors with $SIG{__WARN__}.
241         Be sure to use the libraries and modules shipped with the version 
242           being tested, not those that were already installed.
243         Add comments to the code explaining what you are testing for.
244         Make updating the '1..42' string unnecessary.  Or make sure that 
245           you update it.
246         Test _all_ behaviors of a given operator, library, or function:
247           - All optional arguments
248           - Return values in various contexts (boolean, scalar, list, lvalue)
249           - Use both global and lexical variables
250           - Don't forget the exceptional, pathological cases.
251
252 =back
253
254 =item Test your patch
255
256 Apply your patch to a clean distribution, compile, and run the
257 regression test suite (you did remember to add one for your
258 patch, didn't you).
259
260 =back
261
262 =head2 An example patch creation
263
264 This should work for most patches:
265
266       cp MANIFEST MANIFEST.old
267       emacs MANIFEST
268       (make changes)
269       cd ..
270       diff -c perl5.7.42/MANIFEST.old perl5.7.42/MANIFEST > mypatch
271       (testing the patch:)
272       mv perl5.7.42/MANIFEST perl5.7.42/MANIFEST.new
273       cp perl5.7.42/MANIFEST.old perl5.7.42/MANIFEST
274       patch -p < mypatch
275       (should succeed)
276       diff perl5.7.42/MANIFEST perl5.7.42/MANIFEST.new
277       (should produce no output)
278
279 =head2 Submitting your patch
280
281 =over 4
282
283 =item Mailers
284
285 Please, please, please (get the point? 8-) don't use a mailer that
286 word wraps your patch.  This leaves the patch essentially worthless
287 to the maintainers.
288
289 Unfortunately many mailers word wrap the main text of messages, but
290 luckily you can usually send your patches as email attachments without
291 them getting "helpfully" word wrapped.
292
293 If you have no choice in mailers and no way to get your hands on
294 a better one, there is, of course, a Perl solution.  Just do this:
295
296       perl -ne 'print pack("u*",$_)' patch > patch.uue
297
298 and post patch.uue with a note saying to unpack it using
299
300       perl -ne 'print unpack("u*",$_)' patch.uue > patch
301
302 =item Subject lines for patches
303
304 The subject line on your patch should read
305
306     [PATCH 5.x.x AREA] Description
307
308 where the x's are replaced by the appropriate version number.
309 The description should be a very brief but accurate summary of the
310 problem (don't forget this is an email header).
311
312 Examples:
313
314     [PATCH 5.6.4 DOC] fix minor typos
315
316     [PATCH 5.7.9 CORE] New warning for foo() when frobbing
317
318     [PATCH 5.7.16 CONFIG] Added support for fribnatz 1.5
319
320 The name of the file being patched makes for a poor subject line if
321 no other descriptive text accompanies it.
322
323 =item Where to send your patch
324
325 If your patch is for a specific bug in the Perl core, it should be sent
326 using the perlbug utility.  Don't forget to describe the problem and the
327 fix adequately.
328
329 If it is a patch to a module that you downloaded from CPAN you should
330 submit your patch to that module's author.
331
332 If your patch addresses one of the items described in perltodo.pod,
333 please discuss your approach B<before> you make the patch at
334 <perl5-porters@perl.org>.  Be sure to browse the archives of past
335 discussions (see perltodo.pod for archive locations).
336
337 =back
338
339 =head2 Applying a patch
340
341 =over 4
342
343 =item General notes on applying patches
344
345 The following are some general notes on applying a patch
346 to your perl distribution.
347
348 =over 4
349
350 =item patch C<-p>
351
352 It is generally easier to apply patches with the C<-p N> argument to
353 patch (where N is the number of path components to skip in the files
354 found in the headers).  This helps reconcile differing paths between
355 the machine the patch was created on and the machine on which it is
356 being applied.
357
358 Be sure to use the Larry Wall version of patch. Some Operating Systems
359 (HP-UX amongst those) have a patch command that does something completely
360 different. The correct version of patch will show Larry's name several
361 times when invoked as patch --version.
362
363 =item Cut and paste
364
365 B<Never> cut and paste a patch into your editor.  This usually clobbers
366 the tabs and confuses patch.
367
368 =item Hand editing patches
369
370 Avoid hand editing patches as this almost always screws up the line
371 numbers and offsets in the patch, making it useless.
372
373 =back
374
375 =back
376
377 =head2 Final notes
378
379 If you follow these guidelines it will make everybody's life a little
380 easier.  You'll have the satisfaction of having contributed to perl,
381 others will have an easy time using your work, and it should be easier
382 for the maintainers to coordinate the occasionally large numbers of 
383 patches received.
384
385 Also, just because you're not a brilliant coder doesn't mean that you
386 can't contribute.  As valuable as code patches are there is always a
387 need for better documentation (especially considering the general
388 level of joy that most programmers feel when forced to sit down and
389 write docs).  If all you do is patch the documentation you have still
390 contributed more than the person who sent in an amazing new feature
391 that no one can use because no one understands the code (what I'm
392 getting at is that documentation is both the hardest part to do
393 (because everyone hates doing it) and the most valuable).
394
395 Mostly, when contributing patches, imagine that it is B<you> receiving
396 hundreds of patches and that it is B<your> responsibility to integrate
397 them into the source.  Obviously you'd want the patches to be as easy
398 to apply as possible.  Keep that in mind.  8-)
399
400 =head1 Last Modified
401
402 Last modified 22 August 2002
403 H.Merijn Brand <h.m.brand@hccnet.nl>
404 Prev modified 21 January 1999 
405 Daniel Grisinger <dgris@dimensional.com>
406
407 =head1 Author and Copyright Information
408
409 Copyright (c) 1998-2002 Daniel Grisinger
410
411 Adapted from a posting to perl5-porters by Tim Bunce (Tim.Bunce@ig.co.uk).
412
413 I'd like to thank the perl5-porters for their suggestions.