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
emacs MANIFEST
(make changes)
cd ..
- diff -c perl5.008_42/MANIFEST.old perl5.008_42/MANIFEST > mypatch
+ diff -c perl5.7.42/MANIFEST.old perl5.7.42/MANIFEST > mypatch
(testing the patch:)
- mv perl5.008_42/MANIFEST perl5.008_42/MANIFEST.new
- cp perl5.008_42/MANIFEST.old perl5.008_42/MANIFEST
+ mv perl5.7.42/MANIFEST perl5.7.42/MANIFEST.new
+ cp perl5.7.42/MANIFEST.old perl5.7.42/MANIFEST
patch -p < mypatch
(should succeed)
- diff perl5.008_42/MANIFEST perl5.008_42/MANIFEST.new
+ diff perl5.7.42/MANIFEST perl5.7.42/MANIFEST.new
(should produce no output)
=head2 Submitting your patch
=item Mailers
Please, please, please (get the point? 8-) don't use a mailer that
-word wraps your patch or that MIME encodes it. Both of these leave
-the patch essentially worthless to the maintainer.
+word wraps your patch. This leaves the patch essentially worthless
+to the maintainers.
-If you have no choice in mailers and no way to get your hands on a
-better one there is, of course, a perl solution. Just do this:
+Unfortunately many mailers word wrap the main text of messages, but
+luckily you can usually send your patches as email attachments without
+them getting "helpfully" word wrapped.
+
+If you have no choice in mailers and no way to get your hands on
+a better one, there is, of course, a Perl solution. Just do this:
perl -ne 'print pack("u*",$_)' patch > patch.uue
The subject line on your patch should read
- [PATCH 5.xxx_xx AREA] Description
+ [PATCH 5.x.x AREA] Description
where the x's are replaced by the appropriate version number.
The description should be a very brief but accurate summary of the
Examples:
- [PATCH 5.004_04 DOC] fix minor typos
+ [PATCH 5.6.4 DOC] fix minor typos
- [PATCH 5.004_99 CORE] New warning for foo() when frobbing
+ [PATCH 5.7.9 CORE] New warning for foo() when frobbing
- [PATCH 5.005_42 CONFIG] Added support for fribnatz 1.5
+ [PATCH 5.7.16 CONFIG] Added support for fribnatz 1.5
The name of the file being patched makes for a poor subject line if
no other descriptive text accompanies it.
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 Daniel Grisinger
+Copyright (c) 1998-2002 Daniel Grisinger
Adapted from a posting to perl5-porters by Tim Bunce (Tim.Bunce@ig.co.uk).