Porting/patching.pod

   1 =head1 Name
   2
   3 patching.pod - Appropriate format for patches to the perl source tree
   4
   5 =head2 Where to get this document
   6
   7 The latest version of this document is available from
   8      http://perrin.dimensional.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@dimensional.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 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
  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 ensures 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 The preferred method for creating a unified diff suitable for feeding
  67 to the patch program is:
  68
  69         diff -u old-file new-file > patch-file
  70
  71 Note the order of files.  See below for how to create a patch from
  72 two directory trees.
  73
  74 If your patch is for wider consumption, it may be better to create it as
  75 a context diff as some machines have broken patch utilities that choke on
  76 unified diffs.  A context diff is made using C<diff -c> rather than
  77 C<diff -u>.
  78
  79 GNU diff has many desirable features not provided by most vendor-supplied
  80 diffs.  Some examples using GNU diff:
  81
  82     # generate a patch for a newly added file
  83     % diff -u /dev/null new/file
  84
  85     # generate a patch to remove a file (patch > v2.4 will remove it cleanly)
  86     % diff -u old/goner /dev/null
  87
  88     # get additions, deletions along with everything else, recursively
  89     % diff -ruN olddir newdir
  90
  91     # ignore whitespace
  92     % diff -bu a/file b/file
  93
  94     # show function name in every hunk (safer, more informative)
  95     % diff -u -F '^[_a-zA-Z0-9]+ *(' old/file new/file
  96
  97
  98 =item Directories
  99
 100 IMPORTANT: Patches should be generated from the source root directory, not
 101 from the directory that the patched file resides in.  This ensures that the
 102 maintainer patches the proper file.
 103
 104 Many files in the distribution are derivative--avoid patching them.
 105 Patch the originals instead.  Most utilities (like perldoc) are in
 106 this category, i.e. patch utils/perldoc.PL rather than utils/perldoc.
 107 Similarly, don't create patches for files under $src_root/ext from
 108 their copies found in $install_root/lib.  If you are unsure about the
 109 proper location of a file that may have gotten copied while building
 110 the source distribution, consult the C<MANIFEST>.
 111
 112 =item Filenames
 113
 114 The most usual convention when submitting patches for a single file is to make
 115 your changes to a copy of the file with the same name as the original.  Rename
 116 the original file in such a way that it is obvious what is being patched
 117 ($file.dist or $file.old seem to be popular).
 118
 119 If you are submitting patches that affect multiple files then you should
 120 backup the entire directory tree (to $source_root.old/ for example).  This
 121 will allow C<diff -ruN old-dir new-dir> to create all the patches at once.
 122
 123 =item Try it yourself
 124
 125 Just to make sure your patch "works", be sure to apply it to the Perl
 126 distribution, rebuild everything, and make sure the testsuite runs
 127 without incident.
 128
 129 =back
 130
 131 =head2 What to include in your patch
 132
 133 =over 4
 134
 135 =item Description of problem
 136
 137 The first thing you should include is a description of the problem that
 138 the patch corrects.  If it is a code patch (rather than a documentation
 139 patch) you should also include a small test case that illustrates the
 140 bug.
 141
 142 =item Directions for application
 143
 144 You should include instructions on how to properly apply your patch.
 145 These should include the files affected, any shell scripts or commands
 146 that need to be run before or after application of the patch, and
 147 the command line necessary for application.
 148
 149 =item If you have a code patch
 150
 151 If you are submitting a code patch there are several other things that
 152 you need to do.
 153
 154 =over 4
 155
 156 =item Comments, Comments, Comments
 157
 158 Be sure to adequately comment your code.  While commenting every
 159 line is unnecessary, anything that takes advantage of side effects of
 160 operators, that creates changes that will be felt outside of the
 161 function being patched, or that others may find confusing should
 162 be documented.  If you are going to err, it is better to err on the
 163 side of adding too many comments than too few.
 164
 165 =item Style
 166
 167 In general, please follow the particular style of the code you are patching.
 168
 169 In particular, follow these general guidelines for patching Perl sources:
 170
 171     8-wide tabs (no exceptions!)
 172     4-wide indents for code, 2-wide indents for nested CPP #defines
 173     try hard not to exceed 79-columns
 174     ANSI C prototypes
 175     uncuddled elses and "K&R" style for indenting control constructs
 176     no C++ style (//) comments, most C compilers will choke on them
 177     mark places that need to be revisited with XXX (and revisit often!)
 178     opening brace lines up with "if" when conditional spans multiple
 179         lines; should be at end-of-line otherwise
 180     in function definitions, name starts in column 0 (return value is on
 181         previous line)
 182     single space after keywords that are followed by parens, no space
 183         between function name and following paren
 184     avoid assignments in conditionals, but if they're unavoidable, use
 185         extra paren, e.g. "if (a && (b = c)) ..."
 186     "return foo;" rather than "return(foo);"
 187     "if (!foo) ..." rather than "if (foo == FALSE) ..." etc.
 188
 189
 190 =item Testsuite
 191
 192 When submitting a patch you should make every effort to also include
 193 an addition to perl's regression tests to properly exercise your
 194 patch.  Your testsuite additions should generally follow these
 195 guidelines (courtesy of Gurusamy Sarathy <gsar@activestate.com>):
 196
 197         Know what you're testing.  Read the docs, and the source.
 198         Tend to fail, not succeed.
 199         Interpret results strictly.
 200         Use unrelated features (this will flush out bizarre interactions).
 201         Use non-standard idioms (otherwise you are not testing TIMTOWTDI).
 202         Avoid using hardcoded test numbers whenever possible (the
 203           EXPECTED/GOT found in t/op/tie.t is much more maintainable,
 204           and gives better failure reports).
 205         Give meaningful error messages when a test fails.
 206         Avoid using qx// and system() unless you are testing for them.  If you
 207           do use them, make sure that you cover _all_ perl platforms.
 208         Unlink any temporary files you create.
 209         Promote unforeseen warnings to errors with $SIG{__WARN__}.
 210         Be sure to use the libraries and modules shipped with the version
 211           being tested, not those that were already installed.
 212         Add comments to the code explaining what you are testing for.
 213         Make updating the '1..42' string unnecessary.  Or make sure that
 214           you update it.
 215         Test _all_ behaviors of a given operator, library, or function:
 216           - All optional arguments
 217           - Return values in various contexts (boolean, scalar, list, lvalue)
 218           - Use both global and lexical variables
 219           - Don't forget the exceptional, pathological cases.
 220
 221 =back
 222
 223 =item Test your patch
 224
 225 Apply your patch to a clean distribution, compile, and run the
 226 regression test suite (you did remember to add one for your
 227 patch, didn't you).
 228
 229 =back
 230
 231 =head2 An example patch creation
 232
 233 This should work for most patches:
 234
 235       cp MANIFEST MANIFEST.old
 236       emacs MANIFEST
 237       (make changes)
 238       cd ..
 239       diff -c perl5.008_42/MANIFEST.old perl5.008_42/MANIFEST > mypatch
 240       (testing the patch:)
 241       mv perl5.008_42/MANIFEST perl5.008_42/MANIFEST.new
 242       cp perl5.008_42/MANIFEST.old perl5.008_42/MANIFEST
 243       patch -p < mypatch
 244       (should succeed)
 245       diff perl5.008_42/MANIFEST perl5.008_42/MANIFEST.new
 246       (should produce no output)
 247
 248 =head2 Submitting your patch
 249
 250 =over 4
 251
 252 =item Mailers
 253
 254 Please, please, please (get the point? 8-) don't use a mailer that
 255 word wraps your patch or that MIME encodes it.  Both of these leave
 256 the patch essentially worthless to the maintainer.
 257
 258 If you have no choice in mailers and no way to get your hands on a
 259 better one there is, of course, a perl solution.  Just do this:
 260
 261       perl -ne 'print pack("u*",$_)' patch > patch.uue
 262
 263 and post patch.uue with a note saying to unpack it using
 264
 265       perl -ne 'print unpack("u*",$_)' patch.uue > patch
 266
 267 =item Subject lines for patches
 268
 269 The subject line on your patch should read
 270
 271     [PATCH 5.xxx_xx AREA] Description
 272
 273 where the x's are replaced by the appropriate version number.
 274 The description should be a very brief but accurate summary of the
 275 problem (don't forget this is an email header).
 276
 277 Examples:
 278
 279     [PATCH 5.004_04 DOC] fix minor typos
 280
 281     [PATCH 5.004_99 CORE] New warning for foo() when frobbing
 282
 283     [PATCH 5.005_42 CONFIG] Added support for fribnatz 1.5
 284
 285 The name of the file being patched makes for a poor subject line if
 286 no other descriptive text accompanies it.
 287
 288 =item Where to send your patch
 289
 290 If your patch is for a specific bug in the Perl core, it should be sent
 291 using the perlbug utility.  Don't forget to describe the problem and the
 292 fix adequately.
 293
 294 If it is a patch to a module that you downloaded from CPAN you should
 295 submit your patch to that module's author.
 296
 297 If your patch addresses one of the items described in perltodo.pod,
 298 please discuss your approach B<before> you make the patch at
 299 <perl5-porters@perl.org>.  Be sure to browse the archives of past
 300 discussions (see perltodo.pod for archive locations).
 301
 302 =back
 303
 304 =head2 Applying a patch
 305
 306 =over 4
 307
 308 =item General notes on applying patches
 309
 310 The following are some general notes on applying a patch
 311 to your perl distribution.
 312
 313 =over 4
 314
 315 =item patch C<-p>
 316
 317 It is generally easier to apply patches with the C<-p N> argument to
 318 patch (where N is the number of path components to skip in the files
 319 found in the headers).  This helps reconcile differing paths between
 320 the machine the patch was created on and the machine on which it is
 321 being applied.
 322
 323 =item Cut and paste
 324
 325 B<Never> cut and paste a patch into your editor.  This usually clobbers
 326 the tabs and confuses patch.
 327
 328 =item Hand editing patches
 329
 330 Avoid hand editing patches as this almost always screws up the line
 331 numbers and offsets in the patch, making it useless.
 332
 333 =back
 334
 335 =back
 336
 337 =head2 Final notes
 338
 339 If you follow these guidelines it will make everybody's life a little
 340 easier.  You'll have the satisfaction of having contributed to perl,
 341 others will have an easy time using your work, and it should be easier
 342 for the maintainers to coordinate the occasionally large numbers of
 343 patches received.
 344
 345 Also, just because you're not a brilliant coder doesn't mean that you
 346 can't contribute.  As valuable as code patches are there is always a
 347 need for better documentation (especially considering the general
 348 level of joy that most programmers feel when forced to sit down and
 349 write docs).  If all you do is patch the documentation you have still
 350 contributed more than the person who sent in an amazing new feature
 351 that no one can use because no one understands the code (what I'm
 352 getting at is that documentation is both the hardest part to do
 353 (because everyone hates doing it) and the most valuable).
 354
 355 Mostly, when contributing patches, imagine that it is B<you> receiving
 356 hundreds of patches and that it is B<your> responsibility to integrate
 357 them into the source.  Obviously you'd want the patches to be as easy
 358 to apply as possible.  Keep that in mind.  8-)
 359
 360 =head1 Last Modified
 361
 362 Last modified 21 January 1999
 363 Daniel Grisinger <dgris@dimensional.com>
 364
 365 =head1 Author and Copyright Information
 366
 367 Copyright (c) 1998 Daniel Grisinger
 368
 369 Adapted from a posting to perl5-porters by Tim Bunce (Tim.Bunce@ig.co.uk).
 370
 371 I'd like to thank the perl5-porters for their suggestions.