Commit | Line | Data |
55d729e4 |
1 | =head1 Name |
2 | |
3 | patching.pod - Appropriate format for patches to the perl source tree |
4 | |
5 | =head2re to get this document |
6 | |
7 | The latest version of this document is available from |
8 | http://www.tdrenterprises.com/perl/perlpatch.html |
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 | |
133 | Also please include an addition to the regression tests to properly |
134 | exercise your patch. |
135 | |
136 | =back |
137 | |
138 | =item Test your patch |
139 | |
140 | Apply your patch to a clean distribution, compile, and run the |
141 | regression test suite (you did remember to add one for your |
142 | patch, didn't you). |
143 | |
144 | =back |
145 | |
146 | =head2 An example patch creation |
147 | |
148 | This should work for most patches- |
149 | |
150 | cp MANIFEST MANIFEST.old |
151 | emacs MANIFEST |
152 | (make changes) |
153 | cd .. |
154 | diff -c perl5.008_42/MANIFEST.old perl5.008_42/MANIFEST > mypatch |
155 | (testing the patch:) |
156 | mv perl5.008_42/MANIFEST perl5.008_42/MANIFEST.new |
157 | cp perl5.008_42/MANIFEST.old perl5.008_42/MANIFEST |
158 | patch -p < mypatch |
159 | (should succeed) |
160 | diff perl5.008_42/MANIFEST perl5.008_42/MANIFEST.new |
161 | (should produce no output) |
162 | |
163 | =head2 Submitting your patch |
164 | |
165 | =over 4 |
166 | |
167 | =item Mailers |
168 | |
169 | Please, please, please (get the point? 8-) don't use a mailer that |
170 | word wraps your patch or that MIME encodes it. Both of these leave |
171 | the patch essentially worthless to the maintainer. |
172 | |
173 | If you have no choice in mailers and no way to get your hands on a |
174 | better one there is, of course, a perl solution. Just do this- |
175 | |
176 | perl -ne 'print pack("u*",$_)' patch > patch.uue |
177 | |
178 | and post patch.uue with a note saying to unpack it using |
179 | |
180 | perl -ne 'print unpack("u*",$_)' patch.uue > patch |
181 | |
182 | =item Subject lines for patches |
183 | |
184 | The subject line on your patch should read |
185 | |
186 | [PATCH]5.xxx_xx (Area) Description |
187 | |
188 | where the x's are replaced by the appropriate version number, |
189 | area is a short keyword identifying what area of perl you are |
190 | patching, and description is a very brief summary of the |
191 | problem (don't forget this is an email header). |
192 | |
193 | Examples- |
194 | |
195 | [PATCH]5.004_04 (DOC) fix minor typos |
196 | |
197 | [PATCH]5.004_99 (CORE) New warning for foo() when frobbing |
198 | |
199 | [PATCH]5.005_42 (CONFIG) Added support for fribnatz 1.5 |
200 | |
201 | =item Where to send your patch |
202 | |
203 | If your patch is for the perl core it should be sent perlbug@perl.org. |
204 | If it is a patch to a module that you downloaded from CPAN you should |
205 | submit your patch to that module's author. |
206 | |
207 | =back |
208 | |
209 | =head2 Applying a patch |
210 | |
211 | =over 4 |
212 | |
213 | =item General notes on applying patches |
214 | |
215 | The following are some general notes on applying a patch |
216 | to your perl distribution. |
217 | |
218 | =over 4 |
219 | |
220 | =item patch C<-p> |
221 | |
222 | It is generally easier to apply patches with the C<-p> argument to |
223 | patch. This helps reconcile differing paths between the machine the |
224 | patch was created on and the machine on which it is being applied. |
225 | |
226 | =item Cut and paste |
227 | |
228 | _Never_ cut and paste a patch into your editor. This usually clobbers |
229 | the tabs and confuses patch. |
230 | |
231 | =item Hand editing patches |
232 | |
233 | Avoid hand editing patches as this frequently screws up the whitespace |
234 | in the patch and confuses the patch program. |
235 | |
236 | =back |
237 | |
238 | =back |
239 | |
240 | =head2 Final notes |
241 | |
242 | If you follow these guidelines it will make everybody's life a little |
243 | easier. You'll have the satisfaction of having contributed to perl, |
244 | others will have an easy time using your work, and it should be easier |
245 | for the maintainers to coordinate the occasionally large numbers of |
246 | patches received. |
247 | |
248 | Also, just because you're not a brilliant coder doesn't mean that you can't |
249 | contribute. As valuable as code patches are there is always a need for better |
250 | documentation (especially considering the general level of joy that most |
251 | programmers feel when forced to sit down and write docs). If all you do |
252 | is patch the documentation you have still contributed more than the person |
253 | who sent in an amazing new feature that noone can use because noone understands |
254 | the code (what I'm getting at is that documentation is both the hardest part to |
255 | do (because everyone hates doing it) and the most valuable). |
256 | |
257 | Mostly, when contributing patches, imagine that it is B<you> receiving hundreds |
258 | of patches and that it is B<your> responsibility to integrate them into the source. |
259 | Obviously you'd want the patches to be as easy to apply as possible. Keep that in |
260 | mind. 8-) |
261 | |
262 | =head1 Last Modified |
263 | |
264 | Last modified 1 May 1998 by Daniel Grisinger <dgris@tdrenterprises.com> |
265 | |
266 | =head1 Author and Copyright Information |
267 | |
268 | Copyright (c) 1998 Daniel Grisinger |
269 | |
270 | Adapted from a posting to perl5-porters by Tim Bunce (Tim.Bunce@ig.co.uk). |
271 | |
272 | I'd like to thank the perl5-porters for their suggestions. |
273 | |
274 | |
275 | |