3 patching.pod - Appropriate format for patches to the perl source tree
5 =head2 Where to get this document
7 The latest version of this document is available from
8 http://perrin.dimensional.com/perl/perlpatch.html
10 =head2 How to contribute to this document
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
19 =head2 Why this document exists
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.
29 =head2 Common problems
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).
37 =head1 Proper Patch Guidelines
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.
45 =head2 How to prepare your patch
49 =item Creating your patch
51 First, back up the original files. This can't be stressed enough,
52 back everything up _first_.
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
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.
66 The preferred method for creating a unified diff suitable for feeding
67 to the patch program is:
69 diff -u old-file new-file > patch-file
71 Note the order of files. See below for how to create a patch from
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
79 GNU diff has many desirable features not provided by most vendor-supplied
80 diffs. Some examples using GNU diff:
82 # generate a patch for a newly added file
83 % diff -u /dev/null new/file
85 # generate a patch to remove a file (patch > v2.4 will remove it cleanly)
86 % diff -u old/goner /dev/null
88 # get additions, deletions along with everything else, recursively
89 % diff -ruN olddir newdir
92 % diff -bu a/file b/file
94 # show function name in every hunk (safer, more informative)
95 % diff -u -F '^[_a-zA-Z0-9]+ *(' old/file new/file
99 Many files in the distribution are derivative--avoid patching them.
100 Patch the originals instead. Most utilities (like perldoc) are in
101 this category, i.e. patch utils/perldoc.PL rather than utils/perldoc.
102 Similarly, don't create patches for files under $src_root/ext from
103 their copies found in $install_root/lib. If you are unsure about the
104 proper location of a file that may have gotten copied while building
105 the source distribution, consult the C<MANIFEST>.
109 The most usual convention when submitting patches for a single file is to make
110 your changes to a copy of the file with the same name as the original. Rename
111 the original file in such a way that it is obvious what is being patched
112 ($file.dist or $file.old seem to be popular).
114 If you are submitting patches that affect multiple files then you should
115 backup the entire directory tree (to $source_root.old/ for example). This
116 will allow C<diff -ruN old-dir new-dir> to create all the patches at once.
120 IMPORTANT: Patches should be generated from the source root directory, not
121 from the directory that the patched file resides in. This ensures that the
122 maintainer patches the proper file.
124 For larger patches that are dealing with multiple files or
125 directories, Johan Vromans has written a powerful utility: makepatch.
126 See the JV directory on CPAN for the current version. If you have this
127 program available, it is recommended to create a duplicate of the perl
128 directory tree against which you are intending to provide a patch and
129 let makepatch figure out all the changes you made to your copy of the
130 sources. As perl comes with a MANIFEST file, you need not delete
131 object files and other derivative files from the two directory trees,
132 makepatch is smart about them.
134 Say, you have created a directory perl-5.7.1@8685/ for the perl you
135 are taking as the base and a directory perl-5.7.1@8685-withfoo/ where
136 you have your changes, you would run makepatch as follows:
138 makepatch -oldman perl-5.7.1@8685/MANIFEST \
139 -newman perl-5.7.1@8685-withfoo/MANIFEST \
141 perl-5.7.1@8685 perl-5.7.1@8685-withfoo
143 =item Try it yourself
145 Just to make sure your patch "works", be sure to apply it to the Perl
146 distribution, rebuild everything, and make sure the testsuite runs
151 =head2 What to include in your patch
155 =item Description of problem
157 The first thing you should include is a description of the problem that
158 the patch corrects. If it is a code patch (rather than a documentation
159 patch) you should also include a small test case that illustrates the
162 =item Directions for application
164 You should include instructions on how to properly apply your patch.
165 These should include the files affected, any shell scripts or commands
166 that need to be run before or after application of the patch, and
167 the command line necessary for application.
169 =item If you have a code patch
171 If you are submitting a code patch there are several other things that
176 =item Comments, Comments, Comments
178 Be sure to adequately comment your code. While commenting every
179 line is unnecessary, anything that takes advantage of side effects of
180 operators, that creates changes that will be felt outside of the
181 function being patched, or that others may find confusing should
182 be documented. If you are going to err, it is better to err on the
183 side of adding too many comments than too few.
187 In general, please follow the particular style of the code you are patching.
189 In particular, follow these general guidelines for patching Perl sources:
191 8-wide tabs (no exceptions!)
192 4-wide indents for code, 2-wide indents for nested CPP #defines
193 try hard not to exceed 79-columns
195 uncuddled elses and "K&R" style for indenting control constructs
196 no C++ style (//) comments, most C compilers will choke on them
197 mark places that need to be revisited with XXX (and revisit often!)
198 opening brace lines up with "if" when conditional spans multiple
199 lines; should be at end-of-line otherwise
200 in function definitions, name starts in column 0 (return value is on
202 single space after keywords that are followed by parens, no space
203 between function name and following paren
204 avoid assignments in conditionals, but if they're unavoidable, use
205 extra paren, e.g. "if (a && (b = c)) ..."
206 "return foo;" rather than "return(foo);"
207 "if (!foo) ..." rather than "if (foo == FALSE) ..." etc.
212 When submitting a patch you should make every effort to also include
213 an addition to perl's regression tests to properly exercise your
214 patch. Your testsuite additions should generally follow these
215 guidelines (courtesy of Gurusamy Sarathy <gsar@activestate.com>):
217 Know what you're testing. Read the docs, and the source.
218 Tend to fail, not succeed.
219 Interpret results strictly.
220 Use unrelated features (this will flush out bizarre interactions).
221 Use non-standard idioms (otherwise you are not testing TIMTOWTDI).
222 Avoid using hardcoded test numbers whenever possible (the
223 EXPECTED/GOT found in t/op/tie.t is much more maintainable,
224 and gives better failure reports).
225 Give meaningful error messages when a test fails.
226 Avoid using qx// and system() unless you are testing for them. If you
227 do use them, make sure that you cover _all_ perl platforms.
228 Unlink any temporary files you create.
229 Promote unforeseen warnings to errors with $SIG{__WARN__}.
230 Be sure to use the libraries and modules shipped with the version
231 being tested, not those that were already installed.
232 Add comments to the code explaining what you are testing for.
233 Make updating the '1..42' string unnecessary. Or make sure that
235 Test _all_ behaviors of a given operator, library, or function:
236 - All optional arguments
237 - Return values in various contexts (boolean, scalar, list, lvalue)
238 - Use both global and lexical variables
239 - Don't forget the exceptional, pathological cases.
243 =item Test your patch
245 Apply your patch to a clean distribution, compile, and run the
246 regression test suite (you did remember to add one for your
251 =head2 An example patch creation
253 This should work for most patches:
255 cp MANIFEST MANIFEST.old
259 diff -c perl5.7.42/MANIFEST.old perl5.7.42/MANIFEST > mypatch
261 mv perl5.7.42/MANIFEST perl5.7.42/MANIFEST.new
262 cp perl5.7.42/MANIFEST.old perl5.7.42/MANIFEST
265 diff perl5.7.42/MANIFEST perl5.7.42/MANIFEST.new
266 (should produce no output)
268 =head2 Submitting your patch
274 Please, please, please (get the point? 8-) don't use a mailer that
275 word wraps your patch or that MIME encodes it. Both of these leave
276 the patch essentially worthless to the maintainer.
278 If you have no choice in mailers and no way to get your hands on a
279 better one there is, of course, a perl solution. Just do this:
281 perl -ne 'print pack("u*",$_)' patch > patch.uue
283 and post patch.uue with a note saying to unpack it using
285 perl -ne 'print unpack("u*",$_)' patch.uue > patch
287 =item Subject lines for patches
289 The subject line on your patch should read
291 [PATCH 5.x.x AREA] Description
293 where the x's are replaced by the appropriate version number.
294 The description should be a very brief but accurate summary of the
295 problem (don't forget this is an email header).
299 [PATCH 5.6.4 DOC] fix minor typos
301 [PATCH 5.7.9 CORE] New warning for foo() when frobbing
303 [PATCH 5.7.16 CONFIG] Added support for fribnatz 1.5
305 The name of the file being patched makes for a poor subject line if
306 no other descriptive text accompanies it.
308 =item Where to send your patch
310 If your patch is for a specific bug in the Perl core, it should be sent
311 using the perlbug utility. Don't forget to describe the problem and the
314 If it is a patch to a module that you downloaded from CPAN you should
315 submit your patch to that module's author.
317 If your patch addresses one of the items described in perltodo.pod,
318 please discuss your approach B<before> you make the patch at
319 <perl5-porters@perl.org>. Be sure to browse the archives of past
320 discussions (see perltodo.pod for archive locations).
324 =head2 Applying a patch
328 =item General notes on applying patches
330 The following are some general notes on applying a patch
331 to your perl distribution.
337 It is generally easier to apply patches with the C<-p N> argument to
338 patch (where N is the number of path components to skip in the files
339 found in the headers). This helps reconcile differing paths between
340 the machine the patch was created on and the machine on which it is
345 B<Never> cut and paste a patch into your editor. This usually clobbers
346 the tabs and confuses patch.
348 =item Hand editing patches
350 Avoid hand editing patches as this almost always screws up the line
351 numbers and offsets in the patch, making it useless.
359 If you follow these guidelines it will make everybody's life a little
360 easier. You'll have the satisfaction of having contributed to perl,
361 others will have an easy time using your work, and it should be easier
362 for the maintainers to coordinate the occasionally large numbers of
365 Also, just because you're not a brilliant coder doesn't mean that you
366 can't contribute. As valuable as code patches are there is always a
367 need for better documentation (especially considering the general
368 level of joy that most programmers feel when forced to sit down and
369 write docs). If all you do is patch the documentation you have still
370 contributed more than the person who sent in an amazing new feature
371 that no one can use because no one understands the code (what I'm
372 getting at is that documentation is both the hardest part to do
373 (because everyone hates doing it) and the most valuable).
375 Mostly, when contributing patches, imagine that it is B<you> receiving
376 hundreds of patches and that it is B<your> responsibility to integrate
377 them into the source. Obviously you'd want the patches to be as easy
378 to apply as possible. Keep that in mind. 8-)
382 Last modified 21 January 1999
383 Daniel Grisinger <dgris@dimensional.com>
385 =head1 Author and Copyright Information
387 Copyright (c) 1998, 1999 Daniel Grisinger
389 Adapted from a posting to perl5-porters by Tim Bunce (Tim.Bunce@ig.co.uk).
391 I'd like to thank the perl5-porters for their suggestions.