patching.pod - Appropriate format for patches to the perl source tree
-=head2 Where to get this document
-
-The latest version of this document is available from
- http://perrin.dimensional.com/perl/perlpatch.html
-
=head2 How to contribute to this document
-You may mail corrections, additions, and suggestions to me
-at dgris@dimensional.com but the preferred method would be
-to follow the instructions set forth in this document and
-submit a patch 8-).
+You may mail corrections, additions, and suggestions by following the
+instructions set forth in this document and submitting a patch :).
=head1 Description
to the original) and context diffs (where several lines surrounding the changes
are included). See the manpage for diff for more details.
+When GNU diff is available, the pumpkins would prefer you use C<-u -p>
+(--unified --show-c-function) as arguments for optimal control. The
+examples below will only use -u.
+
The preferred method for creating a unified diff suitable for feeding
to the patch program is:
# generate a patch for a newly added file
% diff -u /dev/null new/file
-
+
# generate a patch to remove a file (patch > v2.4 will remove it cleanly)
% diff -u old/goner /dev/null
-
+
# get additions, deletions along with everything else, recursively
% diff -ruN olddir newdir
-
+
# ignore whitespace
% diff -bu a/file b/file
-
+
# show function name in every hunk (safer, more informative)
+ % diff -u -p old/file new/file
% diff -u -F '^[_a-zA-Z0-9]+ *(' old/file new/file
+ # show sub name in perl files and modules
+ % diff -u -F '^sub' old/file.pm new/file.pm
+
+ # show header in doc patches
+ % diff -u -F '^=head' old/file.pod new/file.pod
+
=item Derived Files
Many files in the distribution are derivative--avoid patching them.
-diff "diff -u" \
perl-5.7.1@8685 perl-5.7.1@8685-withfoo
+=item Binary Files
+
+Since the patch(1) utility cannot deal with binary files, it's important
+that you either avoid the use of binary files in your patch, generate the
+files dynamically, or that you encode any binary files using the
+F<uupacktool.pl> utility.
+
+Assuming you needed to include a gzip-encoded file for a module's test
+suite, you might do this as follows using the F<uupacktool.pl> utility:
+
+ $ perl uupacktool.pl -v -p -D lib/Some/Module/t/src/t.gz
+ Writing lib/Some/Module/t/src/t.gz into lib/Some/Module/t/src/t.gz.packed
+
+This will replace the C<t.gz> file with an encoded counterpart. During
+C<make test>, before any tests are run, perl's Makefile will restore all
+the C<.packed> files mentioned in the MANIFEST to their original name.
+This means that the test suite does not need to be aware of this packing
+scheme and will not need to be altered.
+
=item Try it yourself
Just to make sure your patch "works", be sure to apply it to the Perl
the machine the patch was created on and the machine on which it is
being applied.
+Be sure to use the Larry Wall version of patch. Some Operating Systems
+(HP-UX amongst those) have a patch command that does something completely
+different. The correct version of patch will show Larry's name several
+times when invoked as patch --version.
+
=item Cut and paste
B<Never> cut and paste a patch into your editor. This usually clobbers
If you follow these guidelines it will make everybody's life a little
easier. You'll have the satisfaction of having contributed to perl,
others will have an easy time using your work, and it should be easier
-for the maintainers to coordinate the occasionally large numbers of
+for the maintainers to coordinate the occasionally large numbers of
patches received.
Also, just because you're not a brilliant coder doesn't mean that you
them into the source. Obviously you'd want the patches to be as easy
to apply as possible. Keep that in mind. 8-)
-=head1 Last Modified
-
-Last modified 21 January 1999
-Daniel Grisinger <dgris@dimensional.com>
-
=head1 Author and Copyright Information
-Copyright (c) 1998, 1999 Daniel Grisinger
+Copyright (c) 1998-2002 Daniel Grisinger
Adapted from a posting to perl5-porters by Tim Bunce (Tim.Bunce@ig.co.uk).