add stub docs for ext/B, other minor tweaks
[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@tdrenterprises.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 How to prepare your patch
40
41 =over 4
42
43 =item Creating your patch
44
45 First, back up the original files.  This can't be stressed enough,
46 back everything up _first_.
47
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
50 source tree.
51
52 =item diff
53
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.
59
60 Also, the preferred method for patching is -
61
62 C<diff [C<-c> | C<-u>] E<lt>old-fileE<gt> E<lt>new-fileE<gt>>
63
64 Note the order of files.
65
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.
69
70 GNU diff has many desirable features not provided by most vendor-supplied
71 diffs.  Some examples using GNU diff:
72
73     # generate a patch for a newly added file
74     % diff -u /dev/null new/file
75     
76     # generate a patch to remove a file (patch > v2.4 will remove it cleanly)
77     % diff -u old/goner /dev/null
78     
79     # get additions, deletions along with everything else, recursively
80     % diff -ruN olddir newdir
81     
82     # ignore whitespace
83     % diff -bu a/file b/file
84     
85     # show function name in every hunk (safer, more informative)
86     % diff -u -F '^[_a-zA-Z0-9]+ *(' old/file new/file
87
88
89 =item Directories
90
91 Patches should be generated from the source root directory, not from the
92 directory that the patched file resides in.  This insures that the maintainer
93 patches the proper file and avoids name collisions (especially common when trying
94 to apply patches to files that appear in both $src_root/ext/* and $src_root/lib/*).
95 It is better to diff the file in $src_root/ext than the file in $src_root/lib.
96
97 =item Filenames
98
99 The most usual convention when submitting patches for a single file is to make
100 your changes to a copy of the file with the same name as the original.  Rename
101 the original file in such a way that it is obvious what is being patched ($file~ or
102 $file.old seem to be popular).
103
104 If you are submitting patches that affect multiple files then you should backup
105 the entire directory tree (to $source_root.old/ for example).  This will allow
106 C<diff C<-c> E<lt>old-dirE<gt> E<lt>new-dirE<gt>> to create all the patches
107 at once.
108
109 =back
110
111 =head2 What to include in your patch
112
113 =over 4
114
115 =item Description of problem
116
117 The first thing you should include is a description of the problem that
118 the patch corrects.  If it is a code patch (rather than a documentation
119 patch) you should also include a small test case that illustrates the
120 bug.
121
122 =item Direction for application
123
124 You should include instructions on how to properly apply your patch.
125 These should include the files affected, any shell scripts or commands
126 that need to be run before or after application of the patch, and
127 the command line necessary for application.
128
129 =item If you have a code patch
130
131 If you are submitting a code patch there are several other things that
132 you need to do.
133
134 =over 4
135
136 =item Comments, Comments, Comments
137
138 Be sure to adequately comment your code.  While commenting every
139 line is unnecessary, anything that takes advantage of side effects of
140 operators, that creates changes that will be felt outside of the
141 function being patched, or that others may find confusing should
142 be documented.  If you are going to err, it is better to err on the
143 side of adding too many comments than too few.
144
145 =item Style
146
147 Please follow the indentation style and nesting style in use in the
148 block of code that you are patching.
149
150 =item Testsuite
151
152 When submitting a patch you should make every effort to also include
153 an addition to perl's regression tests to properly exercise your
154 patch.  Your testsuite additions should generally follow these
155 guidelines (courtesy of Gurusamy Sarathy (gsar@engin.umich.edu))-
156
157         Know what you're testing.  Read the docs, and the source.
158         Tend to fail, not succeed.
159         Interpret results strictly.
160         Use unrelated features (this will flush out bizarre interactions).
161         Use non-standard idioms (otherwise you are not testing TIMTOWTDI).
162         Avoid using hardcoded test umbers whenever possible (the EXPECTED/GOT style
163           found in t/op/tie.t is much more maintainable, and gives better failure
164           reports).
165         Give meaningful error messages when a test fails.
166         Avoid using qx// and system() unless you are testing for them.  If you
167           do use them, make sure that you cover _all_ perl platforms.
168         Unlink any temporary files you create.
169         Promote unforeseen warnings to errors with $SIG{__WARN__}.
170         Be sure to use the libraries and modules shipped with version being tested,
171           not those that were already installed.
172         Add comments to the code explaining what you are testing for.
173         Make updating the '1..42' string unnecessary.  Or make sure that you update it.
174         Test _all_ behaviors of a given operator, library, or function-
175           All optional arguments
176           Return values in various contexts (boolean, scalar, list, lvalue)
177           Use both global and lexical variables
178           Don't forget the exceptional, pathological cases.
179
180 =back
181
182 =item Test your patch
183
184 Apply your patch to a clean distribution, compile, and run the
185 regression test suite (you did remember to add one for your
186 patch, didn't you).
187
188 =back
189
190 =head2 An example patch creation
191
192 This should work for most patches-
193
194       cp MANIFEST MANIFEST.old
195       emacs MANIFEST
196       (make changes)
197       cd ..
198       diff -c perl5.008_42/MANIFEST.old perl5.008_42/MANIFEST > mypatch
199       (testing the patch:)
200       mv perl5.008_42/MANIFEST perl5.008_42/MANIFEST.new
201       cp perl5.008_42/MANIFEST.old perl5.008_42/MANIFEST
202       patch -p < mypatch
203       (should succeed)
204       diff perl5.008_42/MANIFEST perl5.008_42/MANIFEST.new
205       (should produce no output)
206
207 =head2 Submitting your patch
208
209 =over 4
210
211 =item Mailers
212
213 Please, please, please (get the point? 8-) don't use a mailer that
214 word wraps your patch or that MIME encodes it.  Both of these leave
215 the patch essentially worthless to the maintainer.
216
217 If you have no choice in mailers and no way to get your hands on a
218 better one there is, of course, a perl solution.  Just do this-
219
220       perl -ne 'print pack("u*",$_)' patch > patch.uue
221
222 and post patch.uue with a note saying to unpack it using
223
224       perl -ne 'print unpack("u*",$_)' patch.uue > patch
225
226 =item Subject lines for patches
227
228 The subject line on your patch should read
229
230 [PATCH]5.xxx_xx (Area) Description
231
232 where the x's are replaced by the appropriate version number,
233 area is a short keyword identifying what area of perl you are
234 patching, and description is a very brief summary of the
235 problem (don't forget this is an email header).
236
237 Examples-
238
239 [PATCH]5.004_04 (DOC) fix minor typos
240
241 [PATCH]5.004_99 (CORE) New warning for foo() when frobbing
242
243 [PATCH]5.005_42 (CONFIG) Added support for fribnatz 1.5
244
245 =item Where to send your patch
246
247 If your patch is for the perl core it should be sent perlbug@perl.org.
248 If it is a patch to a module that you downloaded from CPAN you should
249 submit your patch to that module's author.
250
251 =back
252
253 =head2 Applying a patch
254
255 =over 4
256
257 =item General notes on applying patches
258
259 The following are some general notes on applying a patch
260 to your perl distribution.
261
262 =over 4
263
264 =item patch C<-p>
265
266 It is generally easier to apply patches with the C<-p> argument to
267 patch.  This helps reconcile differing paths between the machine the
268 patch was created on and the machine on which it is being applied.
269
270 =item Cut and paste
271
272 _Never_ cut and paste a patch into your editor.  This usually clobbers
273 the tabs and confuses patch.
274
275 =item Hand editing patches
276
277 Avoid hand editing patches as this frequently screws up the whitespace
278 in the patch and confuses the patch program.
279
280 =back
281
282 =back
283
284 =head2 Final notes
285
286 If you follow these guidelines it will make everybody's life a little
287 easier.  You'll have the satisfaction of having contributed to perl,
288 others will have an easy time using your work, and it should be easier
289 for the maintainers to coordinate the occasionally large numbers of 
290 patches received.
291
292 Also, just because you're not a brilliant coder doesn't mean that you can't
293 contribute.  As valuable as code patches are there is always a need for better
294 documentation (especially considering the general level of joy that most
295 programmers feel when forced to sit down and write docs).  If all you do
296 is patch the documentation you have still contributed more than the person
297 who sent in an amazing new feature that noone can use because noone understands
298 the code (what I'm getting at is that documentation is both the hardest part to
299 do (because everyone hates doing it) and the most valuable).
300
301 Mostly, when contributing patches, imagine that it is B<you> receiving hundreds
302 of patches and that it is B<your> responsibility to integrate them into the source.
303 Obviously you'd want the patches to be as easy to apply as possible.  Keep that in
304 mind.  8-)
305
306 =head1 Last Modified
307
308 Last modified 21 May 1998 by Daniel Grisinger <dgris@perrin.dimensional.com>
309
310 =head1 Author and Copyright Information
311
312 Copyright (c) 1998 Daniel Grisinger
313
314 Adapted from a posting to perl5-porters by Tim Bunce (Tim.Bunce@ig.co.uk).
315
316 I'd like to thank the perl5-porters for their suggestions.
317
318
319