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@tdrenterprises.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
39 =head2 How to prepare your patch
43 =item Creating your patch
45 First, back up the original files. This can't be stressed enough,
46 back everything up _first_.
48 Also, please create patches against a clean distribution of the perl source.
49 This insures that everyone else can apply your patch without clobbering their
54 While individual tastes vary (and are not the point here) patches should
55 be created using either C<-u> or C<-c> arguments to diff. These produce,
56 respectively, unified diffs (where the changed line appears immediately next
57 to the original) and context diffs (where several lines surrounding the changes
58 are included). See the manpage for diff for more details.
60 Also, the preferred method for patching is -
62 C<diff [C<-c> | C<-u>] E<lt>old-fileE<gt> E<lt>new-fileE<gt>>
64 Note the order of files.
66 Also, if your patch is to the core (rather than to a module) it
67 is better to create it as a context diff as some machines have
68 broken patch utilities that choke on unified diffs.
72 Patches should be generated from the source root directory, not from the
73 directory that the patched file resides in. This insures that the maintainer
74 patches the proper file and avoids name collisions (especially common when trying
75 to apply patches to files that appear in both $src_root/ext/* and $src_root/lib/*).
76 It is better to diff the file in $src_root/ext than the file in $src_root/lib.
80 The most usual convention when submitting patches for a single file is to make
81 your changes to a copy of the file with the same name as the original. Rename
82 the original file in such a way that it is obvious what is being patched ($file~ or
83 $file.old seem to be popular).
85 If you are submitting patches that affect multiple files then you should backup
86 the entire directory tree (to $source_root.old/ for example). This will allow
87 C<diff C<-c> E<lt>old-dirE<gt> E<lt>new-dirE<gt>> to create all the patches
92 =head2 What to include in your patch
96 =item Description of problem
98 The first thing you should include is a description of the problem that
99 the patch corrects. If it is a code patch (rather than a documentation
100 patch) you should also include a small test case that illustrates the
103 =item Direction for application
105 You should include instructions on how to properly apply your patch.
106 These should include the files affected, any shell scripts or commands
107 that need to be run before or after application of the patch, and
108 the command line necessary for application.
110 =item If you have a code patch
112 If you are submitting a code patch there are several other things that
117 =item Comments, Comments, Comments
119 Be sure to adequately comment your code. While commenting every
120 line is unnecessary, anything that takes advantage of side effects of
121 operators, that creates changes that will be felt outside of the
122 function being patched, or that others may find confusing should
123 be documented. If you are going to err, it is better to err on the
124 side of adding too many comments than too few.
128 Please follow the indentation style and nesting style in use in the
129 block of code that you are patching.
133 When submitting a patch you should make every effort to also include
134 an addition to perl's regression tests to properly exercise your
135 patch. Your testsuite additions should generally follow these
136 guidelines (courtesy of Gurusamy Sarathy (gsar@engin.umich.edu))-
138 Know what you're testing. Read the docs, and the source.
139 Tend to fail, not succeed.
140 Interpret results strictly.
141 Use unrelated features (this will flush out bizarre interactions).
142 Use non-standard idioms (otherwise you are not testing TIMTOWTDI).
143 Avoid using hardcoded test umbers whenever possible (the EXPECTED/GOT style
144 found in t/op/tie.t is much more maintainable, and gives better failure
146 Give meaningful error messages when a test fails.
147 Avoid using qx// and system() unless you are testing for them. If you
148 do use them, make sure that you cover _all_ perl platforms.
149 Unlink any temporary files you create.
150 Promote unforeseen warnings to errors with $SIG{__WARN__}.
151 Be sure to use the libraries and modules shipped with version being tested,
152 not those that were already installed.
153 Add comments to the code explaining what you are testing for.
154 Make updating the '1..42' string unnecessary. Or make sure that you update it.
155 Test _all_ behaviors of a given operator, library, or function-
156 All optional arguments
157 Return values in various contexts (boolean, scalar, list, lvalue)
158 Use both global and lexical variables
159 Don't forget the exceptional, pathological cases.
163 =item Test your patch
165 Apply your patch to a clean distribution, compile, and run the
166 regression test suite (you did remember to add one for your
171 =head2 An example patch creation
173 This should work for most patches-
175 cp MANIFEST MANIFEST.old
179 diff -c perl5.008_42/MANIFEST.old perl5.008_42/MANIFEST > mypatch
181 mv perl5.008_42/MANIFEST perl5.008_42/MANIFEST.new
182 cp perl5.008_42/MANIFEST.old perl5.008_42/MANIFEST
185 diff perl5.008_42/MANIFEST perl5.008_42/MANIFEST.new
186 (should produce no output)
188 =head2 Submitting your patch
194 Please, please, please (get the point? 8-) don't use a mailer that
195 word wraps your patch or that MIME encodes it. Both of these leave
196 the patch essentially worthless to the maintainer.
198 If you have no choice in mailers and no way to get your hands on a
199 better one there is, of course, a perl solution. Just do this-
201 perl -ne 'print pack("u*",$_)' patch > patch.uue
203 and post patch.uue with a note saying to unpack it using
205 perl -ne 'print unpack("u*",$_)' patch.uue > patch
207 =item Subject lines for patches
209 The subject line on your patch should read
211 [PATCH]5.xxx_xx (Area) Description
213 where the x's are replaced by the appropriate version number,
214 area is a short keyword identifying what area of perl you are
215 patching, and description is a very brief summary of the
216 problem (don't forget this is an email header).
220 [PATCH]5.004_04 (DOC) fix minor typos
222 [PATCH]5.004_99 (CORE) New warning for foo() when frobbing
224 [PATCH]5.005_42 (CONFIG) Added support for fribnatz 1.5
226 =item Where to send your patch
228 If your patch is for the perl core it should be sent perlbug@perl.org.
229 If it is a patch to a module that you downloaded from CPAN you should
230 submit your patch to that module's author.
234 =head2 Applying a patch
238 =item General notes on applying patches
240 The following are some general notes on applying a patch
241 to your perl distribution.
247 It is generally easier to apply patches with the C<-p> argument to
248 patch. This helps reconcile differing paths between the machine the
249 patch was created on and the machine on which it is being applied.
253 _Never_ cut and paste a patch into your editor. This usually clobbers
254 the tabs and confuses patch.
256 =item Hand editing patches
258 Avoid hand editing patches as this frequently screws up the whitespace
259 in the patch and confuses the patch program.
267 If you follow these guidelines it will make everybody's life a little
268 easier. You'll have the satisfaction of having contributed to perl,
269 others will have an easy time using your work, and it should be easier
270 for the maintainers to coordinate the occasionally large numbers of
273 Also, just because you're not a brilliant coder doesn't mean that you can't
274 contribute. As valuable as code patches are there is always a need for better
275 documentation (especially considering the general level of joy that most
276 programmers feel when forced to sit down and write docs). If all you do
277 is patch the documentation you have still contributed more than the person
278 who sent in an amazing new feature that noone can use because noone understands
279 the code (what I'm getting at is that documentation is both the hardest part to
280 do (because everyone hates doing it) and the most valuable).
282 Mostly, when contributing patches, imagine that it is B<you> receiving hundreds
283 of patches and that it is B<your> responsibility to integrate them into the source.
284 Obviously you'd want the patches to be as easy to apply as possible. Keep that in
289 Last modified 21 May 1998 by Daniel Grisinger <dgris@perrin.dimensional.com>
291 =head1 Author and Copyright Information
293 Copyright (c) 1998 Daniel Grisinger
295 Adapted from a posting to perl5-porters by Tim Bunce (Tim.Bunce@ig.co.uk).
297 I'd like to thank the perl5-porters for their suggestions.