Add fchdir() probe (in non-UNIX systems assume it doesn't exist).

[p5sagit/p5-mst-13.2.git] / Porting / patching.pod

diff --git a/Porting/patching.pod b/Porting/patching.pod
index 5659f23..3849051 100644 (file)
--- a/Porting/patching.pod
+++ b/Porting/patching.pod
@@ -94,12 +94,7 @@ diffs.  Some examples using GNU diff:
     # show function name in every hunk (safer, more informative)
     % diff -u -F '^[_a-zA-Z0-9]+ *(' old/file new/file
 
-
-=item Directories
-
-IMPORTANT: Patches should be generated from the source root directory, not
-from the directory that the patched file resides in.  This ensures that the
-maintainer patches the proper file.
+=item Derived Files
 
 Many files in the distribution are derivative--avoid patching them.
 Patch the originals instead.  Most utilities (like perldoc) are in
@@ -120,6 +115,31 @@ If you are submitting patches that affect multiple files then you should
 backup the entire directory tree (to $source_root.old/ for example).  This
 will allow C<diff -ruN old-dir new-dir> to create all the patches at once.
 
+=item Directories
+
+IMPORTANT: Patches should be generated from the source root directory, not
+from the directory that the patched file resides in.  This ensures that the
+maintainer patches the proper file.
+
+For larger patches that are dealing with multiple files or
+directories, Johan Vromans has written a powerful utility: makepatch.
+See the JV directory on CPAN for the current version. If you have this
+program available, it is recommended to create a duplicate of the perl
+directory tree against which you are intending to provide a patch and
+let makepatch figure out all the changes you made to your copy of the
+sources. As perl comes with a MANIFEST file, you need not delete
+object files and other derivative files from the two directory trees,
+makepatch is smart about them.
+
+Say, you have created a directory perl-5.7.1@8685/ for the perl you
+are taking as the base and a directory perl-5.7.1@8685-withfoo/ where
+you have your changes, you would run makepatch as follows:
+
+    makepatch -oldman perl-5.7.1@8685/MANIFEST \
+              -newman perl-5.7.1@8685-withfoo/MANIFEST \
+              -diff "diff -u" \
+              perl-5.7.1@8685 perl-5.7.1@8685-withfoo
+
 =item Try it yourself
 
 Just to make sure your patch "works", be sure to apply it to the Perl
@@ -236,13 +256,13 @@ This should work for most patches:
       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
@@ -268,7 +288,7 @@ and post patch.uue with a note saying to unpack it using
 
 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
@@ -276,11 +296,11 @@ problem (don't forget this is an email header).
 
 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.
@@ -364,7 +384,7 @@ Daniel Grisinger <dgris@dimensional.com>
 
 =head1 Author and Copyright Information
 
-Copyright (c) 1998 Daniel Grisinger
+Copyright (c) 1998, 1999 Daniel Grisinger
 
 Adapted from a posting to perl5-porters by Tim Bunce (Tim.Bunce@ig.co.uk).