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 insures 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 Also, the preferred method for patching is -
68 C<diff [C<-c> | C<-u>] E<lt>old-fileE<gt> E<lt>new-fileE<gt>>
70 Note the order of files.
72 Also, if your patch is to the core (rather than to a module) it
73 is better to create it as a context diff as some machines have
74 broken patch utilities that choke on unified diffs.
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 -F '^[_a-zA-Z0-9]+ *(' old/file new/file
97 Patches should be generated from the source root directory, not from the
98 directory that the patched file resides in. This insures that the maintainer
99 patches the proper file and avoids name collisions (especially common when trying
100 to apply patches to files that appear in both $src_root/ext/* and $src_root/lib/*).
101 It is better to diff the file in $src_root/ext than the file in $src_root/lib.
105 The most usual convention when submitting patches for a single file is to make
106 your changes to a copy of the file with the same name as the original. Rename
107 the original file in such a way that it is obvious what is being patched ($file~ or
108 $file.old seem to be popular).
110 If you are submitting patches that affect multiple files then you should backup
111 the entire directory tree (to $source_root.old/ for example). This will allow
112 C<diff C<-c> E<lt>old-dirE<gt> E<lt>new-dirE<gt>> to create all the patches
117 =head2 What to include in your patch
121 =item Description of problem
123 The first thing you should include is a description of the problem that
124 the patch corrects. If it is a code patch (rather than a documentation
125 patch) you should also include a small test case that illustrates the
128 =item Direction for application
130 You should include instructions on how to properly apply your patch.
131 These should include the files affected, any shell scripts or commands
132 that need to be run before or after application of the patch, and
133 the command line necessary for application.
135 =item If you have a code patch
137 If you are submitting a code patch there are several other things that
142 =item Comments, Comments, Comments
144 Be sure to adequately comment your code. While commenting every
145 line is unnecessary, anything that takes advantage of side effects of
146 operators, that creates changes that will be felt outside of the
147 function being patched, or that others may find confusing should
148 be documented. If you are going to err, it is better to err on the
149 side of adding too many comments than too few.
153 Please follow the indentation style and nesting style in use in the
154 block of code that you are patching.
158 When submitting a patch you should make every effort to also include
159 an addition to perl's regression tests to properly exercise your
160 patch. Your testsuite additions should generally follow these
161 guidelines (courtesy of Gurusamy Sarathy (gsar@engin.umich.edu))-
163 Know what you're testing. Read the docs, and the source.
164 Tend to fail, not succeed.
165 Interpret results strictly.
166 Use unrelated features (this will flush out bizarre interactions).
167 Use non-standard idioms (otherwise you are not testing TIMTOWTDI).
168 Avoid using hardcoded test numbers whenever possible (the
169 EXPECTED/GOT found in t/op/tie.t is much more maintainable,
170 and gives better failure reports).
171 Give meaningful error messages when a test fails.
172 Avoid using qx// and system() unless you are testing for them. If you
173 do use them, make sure that you cover _all_ perl platforms.
174 Unlink any temporary files you create.
175 Promote unforeseen warnings to errors with $SIG{__WARN__}.
176 Be sure to use the libraries and modules shipped with version
177 being tested, not those that were already installed.
178 Add comments to the code explaining what you are testing for.
179 Make updating the '1..42' string unnecessary. Or make sure that
181 Test _all_ behaviors of a given operator, library, or function-
182 All optional arguments
183 Return values in various contexts (boolean, scalar, list, lvalue)
184 Use both global and lexical variables
185 Don't forget the exceptional, pathological cases.
189 =item Test your patch
191 Apply your patch to a clean distribution, compile, and run the
192 regression test suite (you did remember to add one for your
197 =head2 An example patch creation
199 This should work for most patches-
201 cp MANIFEST MANIFEST.old
205 diff -c perl5.008_42/MANIFEST.old perl5.008_42/MANIFEST > mypatch
207 mv perl5.008_42/MANIFEST perl5.008_42/MANIFEST.new
208 cp perl5.008_42/MANIFEST.old perl5.008_42/MANIFEST
211 diff perl5.008_42/MANIFEST perl5.008_42/MANIFEST.new
212 (should produce no output)
214 =head2 Submitting your patch
220 Please, please, please (get the point? 8-) don't use a mailer that
221 word wraps your patch or that MIME encodes it. Both of these leave
222 the patch essentially worthless to the maintainer.
224 If you have no choice in mailers and no way to get your hands on a
225 better one there is, of course, a perl solution. Just do this-
227 perl -ne 'print pack("u*",$_)' patch > patch.uue
229 and post patch.uue with a note saying to unpack it using
231 perl -ne 'print unpack("u*",$_)' patch.uue > patch
233 =item Subject lines for patches
235 The subject line on your patch should read
237 [PATCH]5.xxx_xx (Area) Description
239 where the x's are replaced by the appropriate version number,
240 area is a short keyword identifying what area of perl you are
241 patching, and description is a very brief summary of the
242 problem (don't forget this is an email header).
246 [PATCH]5.004_04 (DOC) fix minor typos
248 [PATCH]5.004_99 (CORE) New warning for foo() when frobbing
250 [PATCH]5.005_42 (CONFIG) Added support for fribnatz 1.5
252 =item Where to send your patch
254 If your patch is for the perl core it should be sent perlbug@perl.org.
255 If it is a patch to a module that you downloaded from CPAN you should
256 submit your patch to that module's author.
260 =head2 Applying a patch
264 =item General notes on applying patches
266 The following are some general notes on applying a patch
267 to your perl distribution.
273 It is generally easier to apply patches with the C<-p> argument to
274 patch. This helps reconcile differing paths between the machine the
275 patch was created on and the machine on which it is being applied.
279 _Never_ cut and paste a patch into your editor. This usually clobbers
280 the tabs and confuses patch.
282 =item Hand editing patches
284 Avoid hand editing patches as this frequently screws up the whitespace
285 in the patch and confuses the patch program.
293 If you follow these guidelines it will make everybody's life a little
294 easier. You'll have the satisfaction of having contributed to perl,
295 others will have an easy time using your work, and it should be easier
296 for the maintainers to coordinate the occasionally large numbers of
299 Also, just because you're not a brilliant coder doesn't mean that you
300 can't contribute. As valuable as code patches are there is always a
301 need for better documentation (especially considering the general
302 level of joy that most programmers feel when forced to sit down and
303 write docs). If all you do is patch the documentation you have still
304 contributed more than the person who sent in an amazing new feature
305 that no one can use because no one understands the code (what I'm
306 getting at is that documentation is both the hardest part to do
307 (because everyone hates doing it) and the most valuable).
309 Mostly, when contributing patches, imagine that it is B<you> receiving
310 hundreds of patches and that it is B<your> responsibility to integrate
311 them into the source. Obviously you'd want the patches to be as easy
312 to apply as possible. Keep that in mind. 8-)
316 Last modified 21 January 1999
317 Daniel Grisinger <dgris@dimensional.com>
319 =head1 Author and Copyright Information
321 Copyright (c) 1998 Daniel Grisinger
323 Adapted from a posting to perl5-porters by Tim Bunce (Tim.Bunce@ig.co.uk).
325 I'd like to thank the perl5-porters for their suggestions.