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