Commit | Line | Data |
---|---|---|
55d729e4 GS |
1 | =head1 Name |
2 | ||
3 | patching.pod - Appropriate format for patches to the perl source tree | |
4 | ||
f4dad39e | 5 | =head2 Where to get this document |
55d729e4 GS |
6 | |
7 | The 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 | ||
12 | You may mail corrections, additions, and suggestions to me | |
f556e4ac | 13 | at dgris@dimensional.com but the preferred method would be |
55d729e4 GS |
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 | ||
f556e4ac DG |
39 | =head2 What to patch |
40 | ||
41 | Generally speaking you should patch the latest development release | |
42 | of perl. The maintainers of the individual branches will see to it | |
43 | that 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 | ||
51 | First, back up the original files. This can't be stressed enough, | |
52 | back everything up _first_. | |
53 | ||
54 | Also, please create patches against a clean distribution of the perl source. | |
55 | This insures that everyone else can apply your patch without clobbering their | |
56 | source tree. | |
57 | ||
58 | =item diff | |
59 | ||
60 | While individual tastes vary (and are not the point here) patches should | |
61 | be created using either C<-u> or C<-c> arguments to diff. These produce, | |
62 | respectively, unified diffs (where the changed line appears immediately next | |
63 | to the original) and context diffs (where several lines surrounding the changes | |
64 | are included). See the manpage for diff for more details. | |
65 | ||
66 | Also, the preferred method for patching is - | |
67 | ||
68 | C<diff [C<-c> | C<-u>] E<lt>old-fileE<gt> E<lt>new-fileE<gt>> | |
69 | ||
70 | Note the order of files. | |
71 | ||
72 | Also, if your patch is to the core (rather than to a module) it | |
73 | is better to create it as a context diff as some machines have | |
74 | broken patch utilities that choke on unified diffs. | |
75 | ||
9e52009c GS |
76 | GNU diff has many desirable features not provided by most vendor-supplied |
77 | diffs. 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 GS |
95 | =item Directories |
96 | ||
97 | Patches should be generated from the source root directory, not from the | |
98 | directory that the patched file resides in. This insures that the maintainer | |
99 | patches the proper file and avoids name collisions (especially common when trying | |
100 | to apply patches to files that appear in both $src_root/ext/* and $src_root/lib/*). | |
101 | It is better to diff the file in $src_root/ext than the file in $src_root/lib. | |
102 | ||
103 | =item Filenames | |
104 | ||
105 | The most usual convention when submitting patches for a single file is to make | |
106 | your changes to a copy of the file with the same name as the original. Rename | |
107 | the original file in such a way that it is obvious what is being patched ($file~ or | |
108 | $file.old seem to be popular). | |
109 | ||
110 | If you are submitting patches that affect multiple files then you should backup | |
111 | the entire directory tree (to $source_root.old/ for example). This will allow | |
112 | C<diff C<-c> E<lt>old-dirE<gt> E<lt>new-dirE<gt>> to create all the patches | |
113 | at once. | |
114 | ||
115 | =back | |
116 | ||
117 | =head2 What to include in your patch | |
118 | ||
119 | =over 4 | |
120 | ||
121 | =item Description of problem | |
122 | ||
123 | The first thing you should include is a description of the problem that | |
124 | the patch corrects. If it is a code patch (rather than a documentation | |
125 | patch) you should also include a small test case that illustrates the | |
126 | bug. | |
127 | ||
128 | =item Direction for application | |
129 | ||
130 | You should include instructions on how to properly apply your patch. | |
131 | These should include the files affected, any shell scripts or commands | |
132 | that need to be run before or after application of the patch, and | |
133 | the command line necessary for application. | |
134 | ||
135 | =item If you have a code patch | |
136 | ||
137 | If you are submitting a code patch there are several other things that | |
138 | you need to do. | |
139 | ||
140 | =over 4 | |
141 | ||
142 | =item Comments, Comments, Comments | |
143 | ||
144 | Be sure to adequately comment your code. While commenting every | |
145 | line is unnecessary, anything that takes advantage of side effects of | |
146 | operators, that creates changes that will be felt outside of the | |
147 | function being patched, or that others may find confusing should | |
148 | be documented. If you are going to err, it is better to err on the | |
149 | side of adding too many comments than too few. | |
150 | ||
151 | =item Style | |
152 | ||
153 | Please follow the indentation style and nesting style in use in the | |
154 | block of code that you are patching. | |
155 | ||
156 | =item Testsuite | |
157 | ||
f4dad39e DG |
158 | When submitting a patch you should make every effort to also include |
159 | an addition to perl's regression tests to properly exercise your | |
160 | patch. Your testsuite additions should generally follow these | |
161 | guidelines (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 DG |
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 DG |
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 DG |
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 DG |
179 | Make updating the '1..42' string unnecessary. Or make sure that |
180 | you update it. | |
f4dad39e DG |
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 GS |
186 | |
187 | =back | |
188 | ||
189 | =item Test your patch | |
190 | ||
191 | Apply your patch to a clean distribution, compile, and run the | |
192 | regression test suite (you did remember to add one for your | |
193 | patch, didn't you). | |
194 | ||
195 | =back | |
196 | ||
197 | =head2 An example patch creation | |
198 | ||
199 | This 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 | ||
220 | Please, please, please (get the point? 8-) don't use a mailer that | |
221 | word wraps your patch or that MIME encodes it. Both of these leave | |
222 | the patch essentially worthless to the maintainer. | |
223 | ||
224 | If you have no choice in mailers and no way to get your hands on a | |
225 | better one there is, of course, a perl solution. Just do this- | |
226 | ||
227 | perl -ne 'print pack("u*",$_)' patch > patch.uue | |
228 | ||
229 | and 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 | ||
235 | The subject line on your patch should read | |
236 | ||
237 | [PATCH]5.xxx_xx (Area) Description | |
238 | ||
239 | where the x's are replaced by the appropriate version number, | |
240 | area is a short keyword identifying what area of perl you are | |
241 | patching, and description is a very brief summary of the | |
242 | problem (don't forget this is an email header). | |
243 | ||
244 | Examples- | |
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 | ||
254 | If your patch is for the perl core it should be sent perlbug@perl.org. | |
255 | If it is a patch to a module that you downloaded from CPAN you should | |
256 | submit 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 | ||
266 | The following are some general notes on applying a patch | |
267 | to your perl distribution. | |
268 | ||
269 | =over 4 | |
270 | ||
271 | =item patch C<-p> | |
272 | ||
273 | It is generally easier to apply patches with the C<-p> argument to | |
274 | patch. This helps reconcile differing paths between the machine the | |
275 | patch 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 | |
280 | the tabs and confuses patch. | |
281 | ||
282 | =item Hand editing patches | |
283 | ||
284 | Avoid hand editing patches as this frequently screws up the whitespace | |
285 | in the patch and confuses the patch program. | |
286 | ||
287 | =back | |
288 | ||
289 | =back | |
290 | ||
291 | =head2 Final notes | |
292 | ||
293 | If you follow these guidelines it will make everybody's life a little | |
294 | easier. You'll have the satisfaction of having contributed to perl, | |
295 | others will have an easy time using your work, and it should be easier | |
296 | for the maintainers to coordinate the occasionally large numbers of | |
297 | patches received. | |
298 | ||
f556e4ac DG |
299 | Also, just because you're not a brilliant coder doesn't mean that you |
300 | can't contribute. As valuable as code patches are there is always a | |
301 | need for better documentation (especially considering the general | |
302 | level of joy that most programmers feel when forced to sit down and | |
303 | write docs). If all you do is patch the documentation you have still | |
304 | contributed more than the person who sent in an amazing new feature | |
305 | that no one can use because no one understands the code (what I'm | |
306 | getting at is that documentation is both the hardest part to do | |
307 | (because everyone hates doing it) and the most valuable). | |
308 | ||
309 | Mostly, when contributing patches, imagine that it is B<you> receiving | |
310 | hundreds of patches and that it is B<your> responsibility to integrate | |
311 | them into the source. Obviously you'd want the patches to be as easy | |
312 | to apply as possible. Keep that in mind. 8-) | |
55d729e4 GS |
313 | |
314 | =head1 Last Modified | |
315 | ||
f556e4ac DG |
316 | Last modified 21 January 1999 |
317 | Daniel Grisinger <dgris@dimensional.com> | |
55d729e4 GS |
318 | |
319 | =head1 Author and Copyright Information | |
320 | ||
321 | Copyright (c) 1998 Daniel Grisinger | |
322 | ||
323 | Adapted from a posting to perl5-porters by Tim Bunce (Tim.Bunce@ig.co.uk). | |
324 | ||
325 | I'd like to thank the perl5-porters for their suggestions. |