This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
support USE_THREADS+MULTIPLICITY; source compat tweaks for
[perl5.git] / Porting / patching.pod
CommitLineData
55d729e4
GS
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
GS
6
7The latest version of this document is available from
f4dad39e 8 http://perrin.dimensional.com/perl/perlpatch.html
55d729e4
GS
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
GS
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
GS
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
DG
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
GS
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
GS
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
54aff467
GS
66The preferred method for creating a unified diff suitable for feeding
67to the patch program is:
55d729e4 68
54aff467 69 diff -u old-file new-file > patch-file
55d729e4 70
54aff467
GS
71Note the order of files. See below for how to create a patch from
72two directory trees.
55d729e4 73
54aff467
GS
74If your patch is for wider consumption, it may be better to create it as
75a context diff as some machines have broken patch utilities that choke on
76unified diffs. A context diff is made using C<diff -c> rather than
77C<diff -u>.
55d729e4 78
9e52009c
GS
79GNU diff has many desirable features not provided by most vendor-supplied
80diffs. Some examples using GNU diff:
81
82 # generate a patch for a newly added file
83 % diff -u /dev/null new/file
84
85 # generate a patch to remove a file (patch > v2.4 will remove it cleanly)
86 % diff -u old/goner /dev/null
87
88 # get additions, deletions along with everything else, recursively
89 % diff -ruN olddir newdir
90
91 # ignore whitespace
92 % diff -bu a/file b/file
93
94 # show function name in every hunk (safer, more informative)
95 % diff -u -F '^[_a-zA-Z0-9]+ *(' old/file new/file
96
97
55d729e4
GS
98=item Directories
99
54aff467
GS
100IMPORTANT: Patches should be generated from the source root directory, not
101from the directory that the patched file resides in. This ensures that the
102maintainer patches the proper file.
103
104Many files in the distribution are derivative--avoid patching them.
105Patch the originals instead. Most utilities (like perldoc) are in
106this category, i.e. patch utils/perldoc.PL rather than utils/perldoc.
107Similarly, don't create patches for files under $src_root/ext from
108their copies found in $install_root/lib. If you are unsure about the
109proper location of a file that may have gotten copied while building
110the source distribution, consult the C<MANIFEST>.
55d729e4
GS
111
112=item Filenames
113
114The most usual convention when submitting patches for a single file is to make
115your changes to a copy of the file with the same name as the original. Rename
54aff467
GS
116the original file in such a way that it is obvious what is being patched
117($file.dist or $file.old seem to be popular).
118
119If you are submitting patches that affect multiple files then you should
120backup the entire directory tree (to $source_root.old/ for example). This
121will allow C<diff -ruN old-dir new-dir> to create all the patches at once.
55d729e4 122
54aff467
GS
123=item Try it yourself
124
125Just to make sure your patch "works", be sure to apply it to the Perl
126distribution, rebuild everything, and make sure the testsuite runs
127without incident.
55d729e4
GS
128
129=back
130
131=head2 What to include in your patch
132
133=over 4
134
135=item Description of problem
136
137The first thing you should include is a description of the problem that
138the patch corrects. If it is a code patch (rather than a documentation
139patch) you should also include a small test case that illustrates the
140bug.
141
54aff467 142=item Directions for application
55d729e4
GS
143
144You should include instructions on how to properly apply your patch.
145These should include the files affected, any shell scripts or commands
146that need to be run before or after application of the patch, and
147the command line necessary for application.
148
149=item If you have a code patch
150
151If you are submitting a code patch there are several other things that
152you need to do.
153
154=over 4
155
156=item Comments, Comments, Comments
157
158Be sure to adequately comment your code. While commenting every
159line is unnecessary, anything that takes advantage of side effects of
160operators, that creates changes that will be felt outside of the
161function being patched, or that others may find confusing should
162be documented. If you are going to err, it is better to err on the
163side of adding too many comments than too few.
164
165=item Style
166
54aff467
GS
167In general, please follow the particular style of the code you are patching.
168
169In particular, follow these general guidelines for patching Perl sources:
170
171 8-wide tabs (no exceptions!)
172 4-wide indents for code, 2-wide indents for nested CPP #defines
173 try hard not to exceed 79-columns
174 ANSI C prototypes
175 uncuddled elses and "K&R" style for indenting control constructs
176 no C++ style (//) comments, most C compilers will choke on them
177 mark places that need to be revisited with XXX (and revisit often!)
178 opening brace lines up with "if" when conditional spans multiple
179 lines; should be at end-of-line otherwise
180 in function definitions, name starts in column 0 (return value is on
181 previous line)
182 single space after keywords that are followed by parens, no space
183 between function name and following paren
184 avoid assignments in conditionals, but if they're unavoidable, use
185 extra paren, e.g. "if (a && (b = c)) ..."
186 "return foo;" rather than "return(foo);"
187 "if (!foo) ..." rather than "if (foo == FALSE) ..." etc.
188
55d729e4
GS
189
190=item Testsuite
191
f4dad39e
DG
192When submitting a patch you should make every effort to also include
193an addition to perl's regression tests to properly exercise your
194patch. Your testsuite additions should generally follow these
54aff467 195guidelines (courtesy of Gurusamy Sarathy <gsar@activestate.com>):
f4dad39e
DG
196
197 Know what you're testing. Read the docs, and the source.
198 Tend to fail, not succeed.
199 Interpret results strictly.
200 Use unrelated features (this will flush out bizarre interactions).
201 Use non-standard idioms (otherwise you are not testing TIMTOWTDI).
f556e4ac
DG
202 Avoid using hardcoded test numbers whenever possible (the
203 EXPECTED/GOT found in t/op/tie.t is much more maintainable,
204 and gives better failure reports).
f4dad39e
DG
205 Give meaningful error messages when a test fails.
206 Avoid using qx// and system() unless you are testing for them. If you
207 do use them, make sure that you cover _all_ perl platforms.
208 Unlink any temporary files you create.
209 Promote unforeseen warnings to errors with $SIG{__WARN__}.
54aff467 210 Be sure to use the libraries and modules shipped with the version
f556e4ac 211 being tested, not those that were already installed.
f4dad39e 212 Add comments to the code explaining what you are testing for.
f556e4ac
DG
213 Make updating the '1..42' string unnecessary. Or make sure that
214 you update it.
54aff467
GS
215 Test _all_ behaviors of a given operator, library, or function:
216 - All optional arguments
217 - Return values in various contexts (boolean, scalar, list, lvalue)
218 - Use both global and lexical variables
219 - Don't forget the exceptional, pathological cases.
55d729e4
GS
220
221=back
222
223=item Test your patch
224
225Apply your patch to a clean distribution, compile, and run the
226regression test suite (you did remember to add one for your
227patch, didn't you).
228
229=back
230
231=head2 An example patch creation
232
54aff467 233This should work for most patches:
55d729e4
GS
234
235 cp MANIFEST MANIFEST.old
236 emacs MANIFEST
237 (make changes)
238 cd ..
239 diff -c perl5.008_42/MANIFEST.old perl5.008_42/MANIFEST > mypatch
240 (testing the patch:)
241 mv perl5.008_42/MANIFEST perl5.008_42/MANIFEST.new
242 cp perl5.008_42/MANIFEST.old perl5.008_42/MANIFEST
243 patch -p < mypatch
244 (should succeed)
245 diff perl5.008_42/MANIFEST perl5.008_42/MANIFEST.new
246 (should produce no output)
247
248=head2 Submitting your patch
249
250=over 4
251
252=item Mailers
253
254Please, please, please (get the point? 8-) don't use a mailer that
255word wraps your patch or that MIME encodes it. Both of these leave
256the patch essentially worthless to the maintainer.
257
258If you have no choice in mailers and no way to get your hands on a
54aff467 259better one there is, of course, a perl solution. Just do this:
55d729e4
GS
260
261 perl -ne 'print pack("u*",$_)' patch > patch.uue
262
263and post patch.uue with a note saying to unpack it using
264
265 perl -ne 'print unpack("u*",$_)' patch.uue > patch
266
267=item Subject lines for patches
268
269The subject line on your patch should read
270
54aff467 271 [PATCH 5.xxx_xx AREA] Description
55d729e4 272
54aff467
GS
273where the x's are replaced by the appropriate version number.
274The description should be a very brief but accurate summary of the
55d729e4
GS
275problem (don't forget this is an email header).
276
54aff467 277Examples:
55d729e4 278
54aff467 279 [PATCH 5.004_04 DOC] fix minor typos
55d729e4 280
54aff467 281 [PATCH 5.004_99 CORE] New warning for foo() when frobbing
55d729e4 282
54aff467
GS
283 [PATCH 5.005_42 CONFIG] Added support for fribnatz 1.5
284
285The name of the file being patched makes for a poor subject line if
286no other descriptive text accompanies it.
55d729e4
GS
287
288=item Where to send your patch
289
54aff467
GS
290If your patch is for a specific bug in the Perl core, it should be sent
291using the perlbug utility. Don't forget to describe the problem and the
292fix adequately.
293
55d729e4
GS
294If it is a patch to a module that you downloaded from CPAN you should
295submit your patch to that module's author.
296
54aff467
GS
297If your patch addresses one of the items described in perltodo.pod,
298please discuss your approach B<before> you make the patch at
299<perl5-porters@perl.org>. Be sure to browse the archives of past
300discussions (see perltodo.pod for archive locations).
301
55d729e4
GS
302=back
303
304=head2 Applying a patch
305
306=over 4
307
308=item General notes on applying patches
309
310The following are some general notes on applying a patch
311to your perl distribution.
312
313=over 4
314
315=item patch C<-p>
316
54aff467
GS
317It is generally easier to apply patches with the C<-p N> argument to
318patch (where N is the number of path components to skip in the files
319found in the headers). This helps reconcile differing paths between
320the machine the patch was created on and the machine on which it is
321being applied.
55d729e4
GS
322
323=item Cut and paste
324
54aff467 325B<Never> cut and paste a patch into your editor. This usually clobbers
55d729e4
GS
326the tabs and confuses patch.
327
328=item Hand editing patches
329
54aff467
GS
330Avoid hand editing patches as this almost always screws up the line
331numbers and offsets in the patch, making it useless.
55d729e4
GS
332
333=back
334
335=back
336
337=head2 Final notes
338
339If you follow these guidelines it will make everybody's life a little
340easier. You'll have the satisfaction of having contributed to perl,
341others will have an easy time using your work, and it should be easier
342for the maintainers to coordinate the occasionally large numbers of
343patches received.
344
f556e4ac
DG
345Also, just because you're not a brilliant coder doesn't mean that you
346can't contribute. As valuable as code patches are there is always a
347need for better documentation (especially considering the general
348level of joy that most programmers feel when forced to sit down and
349write docs). If all you do is patch the documentation you have still
350contributed more than the person who sent in an amazing new feature
351that no one can use because no one understands the code (what I'm
352getting at is that documentation is both the hardest part to do
353(because everyone hates doing it) and the most valuable).
354
355Mostly, when contributing patches, imagine that it is B<you> receiving
356hundreds of patches and that it is B<your> responsibility to integrate
357them into the source. Obviously you'd want the patches to be as easy
358to apply as possible. Keep that in mind. 8-)
55d729e4
GS
359
360=head1 Last Modified
361
f556e4ac
DG
362Last modified 21 January 1999
363Daniel Grisinger <dgris@dimensional.com>
55d729e4
GS
364
365=head1 Author and Copyright Information
366
367Copyright (c) 1998 Daniel Grisinger
368
369Adapted from a posting to perl5-porters by Tim Bunce (Tim.Bunce@ig.co.uk).
370
371I'd like to thank the perl5-porters for their suggestions.