Porting/patching.pod

   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