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