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