3 patching.pod - Appropriate format for patches to the perl source tree
5 =head2 How to contribute to this document
7 You may mail corrections, additions, and suggestions by following the
8 instructions set forth in this document and submitting a patch :).
12 =head2 Why this document exists
14 As an open source project Perl relies on patches and contributions from
15 its users to continue functioning properly and to root out the inevitable
16 bugs. But, some users are unsure as to the I<right> way to prepare a patch
17 and end up submitting seriously malformed patches. This makes it very
18 difficult for the current maintainer to integrate said patches into their
19 distribution. This document sets out usage guidelines for patches in an
20 attempt to make everybody's life easier.
22 =head2 Common problems
24 The most common problems appear to be patches being mangled by certain
25 mailers (I won't name names, but most of these seem to be originating on
26 boxes running a certain popular commercial operating system). Other problems
27 include patches not rooted in the appropriate place in the directory structure,
28 and patches not produced using standard utilities (such as diff).
30 =head1 Proper Patch Guidelines
34 Generally speaking you should patch the latest development release
35 of perl. The maintainers of the individual branches will see to it
36 that patches are picked up and applied as appropriate.
38 =head2 How to prepare your patch
42 =item Creating your patch
44 First, back up the original files. This can't be stressed enough,
45 back everything up _first_.
47 Also, please create patches against a clean distribution of the perl source.
48 This ensures that everyone else can apply your patch without clobbering their
53 While individual tastes vary (and are not the point here) patches should
54 be created using either C<-u> or C<-c> arguments to diff. These produce,
55 respectively, unified diffs (where the changed line appears immediately next
56 to the original) and context diffs (where several lines surrounding the changes
57 are included). See the manpage for diff for more details.
59 When GNU diff is available, the pumpkins would prefer you use C<-u -p>
60 (--unified --show-c-function) as arguments for optimal control. The
61 examples below will only use -u.
63 The preferred method for creating a unified diff suitable for feeding
64 to the patch program is:
66 diff -u old-file new-file > patch-file
68 Note the order of files. See below for how to create a patch from
71 If your patch is for wider consumption, it may be better to create it as
72 a context diff as some machines have broken patch utilities that choke on
73 unified diffs. A context diff is made using C<diff -c> rather than
76 GNU diff has many desirable features not provided by most vendor-supplied
77 diffs. Some examples using GNU diff:
79 # generate a patch for a newly added file
80 % diff -u /dev/null new/file
82 # generate a patch to remove a file (patch > v2.4 will remove it cleanly)
83 % diff -u old/goner /dev/null
85 # get additions, deletions along with everything else, recursively
86 % diff -ruN olddir newdir
89 % diff -bu a/file b/file
91 # show function name in every hunk (safer, more informative)
92 % diff -u -p old/file new/file
93 % diff -u -F '^[_a-zA-Z0-9]+ *(' old/file new/file
95 # show sub name in perl files and modules
96 % diff -u -F '^sub' old/file.pm new/file.pm
98 # show header in doc patches
99 % diff -u -F '^=head' old/file.pod new/file.pod
103 Many files in the distribution are derivative--avoid patching them.
104 Patch the originals instead. Most utilities (like perldoc) are in
105 this category, i.e. patch utils/perldoc.PL rather than utils/perldoc.
106 Similarly, don't create patches for files under $src_root/ext from
107 their copies found in $install_root/lib. If you are unsure about the
108 proper location of a file that may have gotten copied while building
109 the source distribution, consult the C<MANIFEST>.
113 The most usual convention when submitting patches for a single file is to make
114 your changes to a copy of the file with the same name as the original. Rename
115 the original file in such a way that it is obvious what is being patched
116 ($file.dist or $file.old seem to be popular).
118 If you are submitting patches that affect multiple files then you should
119 backup the entire directory tree (to $source_root.old/ for example). This
120 will allow C<diff -ruN old-dir new-dir> to create all the patches at once.
124 IMPORTANT: Patches should be generated from the source root directory, not
125 from the directory that the patched file resides in. This ensures that the
126 maintainer patches the proper file.
128 For larger patches that are dealing with multiple files or
129 directories, Johan Vromans has written a powerful utility: makepatch.
130 See the JV directory on CPAN for the current version. If you have this
131 program available, it is recommended to create a duplicate of the perl
132 directory tree against which you are intending to provide a patch and
133 let makepatch figure out all the changes you made to your copy of the
134 sources. As perl comes with a MANIFEST file, you need not delete
135 object files and other derivative files from the two directory trees,
136 makepatch is smart about them.
138 Say, you have created a directory perl-5.7.1@8685/ for the perl you
139 are taking as the base and a directory perl-5.7.1@8685-withfoo/ where
140 you have your changes, you would run makepatch as follows:
142 makepatch -oldman perl-5.7.1@8685/MANIFEST \
143 -newman perl-5.7.1@8685-withfoo/MANIFEST \
145 perl-5.7.1@8685 perl-5.7.1@8685-withfoo
149 Since the patch(1) utility cannot deal with binary files, it's important
150 that you either avoid the use of binary files in your patch, generate the
151 files dynamically, or that you encode any binary files using the
152 F<uupacktool.pl> utility.
154 Assuming you needed to include a gzip-encoded file for a module's test
155 suite, you might do this as follows using the F<uupacktool.pl> utility:
157 $ perl uupacktool.pl -v -p -D lib/Some/Module/t/src/t.gz
158 Writing lib/Some/Module/t/src/t.gz into lib/Some/Module/t/src/t.gz.packed
160 This will replace the C<t.gz> file with an encoded counterpart. During
161 C<make test>, before any tests are run, perl's Makefile will restore all
162 the C<.packed> files mentioned in the MANIFEST to their original name.
163 This means that the test suite does not need to be aware of this packing
164 scheme and will not need to be altered.
166 =item Try it yourself
168 Just to make sure your patch "works", be sure to apply it to the Perl
169 distribution, rebuild everything, and make sure the testsuite runs
174 =head2 What to include in your patch
178 =item Description of problem
180 The first thing you should include is a description of the problem that
181 the patch corrects. If it is a code patch (rather than a documentation
182 patch) you should also include a small test case that illustrates the
185 =item Directions for application
187 You should include instructions on how to properly apply your patch.
188 These should include the files affected, any shell scripts or commands
189 that need to be run before or after application of the patch, and
190 the command line necessary for application.
192 =item If you have a code patch
194 If you are submitting a code patch there are several other things that
199 =item Comments, Comments, Comments
201 Be sure to adequately comment your code. While commenting every
202 line is unnecessary, anything that takes advantage of side effects of
203 operators, that creates changes that will be felt outside of the
204 function being patched, or that others may find confusing should
205 be documented. If you are going to err, it is better to err on the
206 side of adding too many comments than too few.
210 In general, please follow the particular style of the code you are patching.
212 In particular, follow these general guidelines for patching Perl sources:
214 8-wide tabs (no exceptions!)
215 4-wide indents for code, 2-wide indents for nested CPP #defines
216 try hard not to exceed 79-columns
218 uncuddled elses and "K&R" style for indenting control constructs
219 no C++ style (//) comments, most C compilers will choke on them
220 mark places that need to be revisited with XXX (and revisit often!)
221 opening brace lines up with "if" when conditional spans multiple
222 lines; should be at end-of-line otherwise
223 in function definitions, name starts in column 0 (return value is on
225 single space after keywords that are followed by parens, no space
226 between function name and following paren
227 avoid assignments in conditionals, but if they're unavoidable, use
228 extra paren, e.g. "if (a && (b = c)) ..."
229 "return foo;" rather than "return(foo);"
230 "if (!foo) ..." rather than "if (foo == FALSE) ..." etc.
235 When submitting a patch you should make every effort to also include
236 an addition to perl's regression tests to properly exercise your
237 patch. Your testsuite additions should generally follow these
238 guidelines (courtesy of Gurusamy Sarathy <gsar@activestate.com>):
240 Know what you're testing. Read the docs, and the source.
241 Tend to fail, not succeed.
242 Interpret results strictly.
243 Use unrelated features (this will flush out bizarre interactions).
244 Use non-standard idioms (otherwise you are not testing TIMTOWTDI).
245 Avoid using hardcoded test numbers whenever possible (the
246 EXPECTED/GOT found in t/op/tie.t is much more maintainable,
247 and gives better failure reports).
248 Give meaningful error messages when a test fails.
249 Avoid using qx// and system() unless you are testing for them. If you
250 do use them, make sure that you cover _all_ perl platforms.
251 Unlink any temporary files you create.
252 Promote unforeseen warnings to errors with $SIG{__WARN__}.
253 Be sure to use the libraries and modules shipped with the version
254 being tested, not those that were already installed.
255 Add comments to the code explaining what you are testing for.
256 Make updating the '1..42' string unnecessary. Or make sure that
258 Test _all_ behaviors of a given operator, library, or function:
259 - All optional arguments
260 - Return values in various contexts (boolean, scalar, list, lvalue)
261 - Use both global and lexical variables
262 - Don't forget the exceptional, pathological cases.
266 =item Test your patch
268 Apply your patch to a clean distribution, compile, and run the
269 regression test suite (you did remember to add one for your
274 =head2 An example patch creation
276 This should work for most patches:
278 cp MANIFEST MANIFEST.old
282 diff -c perl5.7.42/MANIFEST.old perl5.7.42/MANIFEST > mypatch
284 mv perl5.7.42/MANIFEST perl5.7.42/MANIFEST.new
285 cp perl5.7.42/MANIFEST.old perl5.7.42/MANIFEST
288 diff perl5.7.42/MANIFEST perl5.7.42/MANIFEST.new
289 (should produce no output)
291 =head2 Submitting your patch
297 Please, please, please (get the point? 8-) don't use a mailer that
298 word wraps your patch. This leaves the patch essentially worthless
301 Unfortunately many mailers word wrap the main text of messages, but
302 luckily you can usually send your patches as email attachments without
303 them getting "helpfully" word wrapped.
305 If you have no choice in mailers and no way to get your hands on
306 a better one, there is, of course, a Perl solution. Just do this:
308 perl -ne 'print pack("u*",$_)' patch > patch.uue
310 and post patch.uue with a note saying to unpack it using
312 perl -ne 'print unpack("u*",$_)' patch.uue > patch
314 =item Subject lines for patches
316 The subject line on your patch should read
318 [PATCH 5.x.x AREA] Description
320 where the x's are replaced by the appropriate version number.
321 The description should be a very brief but accurate summary of the
322 problem (don't forget this is an email header).
326 [PATCH 5.6.4 DOC] fix minor typos
328 [PATCH 5.7.9 CORE] New warning for foo() when frobbing
330 [PATCH 5.7.16 CONFIG] Added support for fribnatz 1.5
332 The name of the file being patched makes for a poor subject line if
333 no other descriptive text accompanies it.
335 =item Where to send your patch
337 If your patch is for a specific bug in the Perl core, it should be sent
338 using the perlbug utility. Don't forget to describe the problem and the
341 If it is a patch to a module that you downloaded from CPAN you should
342 submit your patch to that module's author.
344 If your patch addresses one of the items described in perltodo.pod,
345 please discuss your approach B<before> you make the patch at
346 <perl5-porters@perl.org>. Be sure to browse the archives of past
347 discussions (see perltodo.pod for archive locations).
351 =head2 Applying a patch
355 =item General notes on applying patches
357 The following are some general notes on applying a patch
358 to your perl distribution.
364 It is generally easier to apply patches with the C<-p N> argument to
365 patch (where N is the number of path components to skip in the files
366 found in the headers). This helps reconcile differing paths between
367 the machine the patch was created on and the machine on which it is
370 Be sure to use the Larry Wall version of patch. Some Operating Systems
371 (HP-UX amongst those) have a patch command that does something completely
372 different. The correct version of patch will show Larry's name several
373 times when invoked as patch --version.
377 B<Never> cut and paste a patch into your editor. This usually clobbers
378 the tabs and confuses patch.
380 =item Hand editing patches
382 Avoid hand editing patches as this almost always screws up the line
383 numbers and offsets in the patch, making it useless.
391 If you follow these guidelines it will make everybody's life a little
392 easier. You'll have the satisfaction of having contributed to perl,
393 others will have an easy time using your work, and it should be easier
394 for the maintainers to coordinate the occasionally large numbers of
397 Also, just because you're not a brilliant coder doesn't mean that you
398 can't contribute. As valuable as code patches are there is always a
399 need for better documentation (especially considering the general
400 level of joy that most programmers feel when forced to sit down and
401 write docs). If all you do is patch the documentation you have still
402 contributed more than the person who sent in an amazing new feature
403 that no one can use because no one understands the code (what I'm
404 getting at is that documentation is both the hardest part to do
405 (because everyone hates doing it) and the most valuable).
407 Mostly, when contributing patches, imagine that it is B<you> receiving
408 hundreds of patches and that it is B<your> responsibility to integrate
409 them into the source. Obviously you'd want the patches to be as easy
410 to apply as possible. Keep that in mind. 8-)
412 =head1 Author and Copyright Information
414 Copyright (c) 1998-2002 Daniel Grisinger
416 Adapted from a posting to perl5-porters by Tim Bunce (Tim.Bunce@ig.co.uk).
418 I'd like to thank the perl5-porters for their suggestions.