[difference between patch application from Change 913 and Change 922]timinator

 ------  DOCUMENTATION  ------

 Title:  "tweak doc for C<do FILENAME>"
  From:  Gurusamy Sarathy <gsar@engin.umich.edu>
Msg-ID:  <199805090017.UAA06888@aatma.engin.umich.edu>
 Files:  pod/perlfunc.pod

 ------  PORTABILITY - GENERAL  ------

 Title:  "Add Porting/patching.pod document"
  From:  Daniel Grisinger <dgris@tdrenterprises.com>
Msg-ID:  <199805030305.XAA16147@relay.pair.com>
 Files:  MANIFEST Porting/patching.pod

 Title:  "Add VMS specifics to Porting/makerel"
  From:  Charles Bailey <BAILEY@newman.upenn.edu>
Msg-ID:  <01IWDK1LONRQ0026P0@cor.newman.upenn.edu>,
         <199804271732.SAA13762@toad.ig.co.uk>,
         <9804250212.AA27695@forte.com>
 Files:  Porting/makerel

p4raw-link: @913 on //depot/maint-5.004/perl: 91b1e15505068510ec71d8e011102933bbe41b37
p4raw-id: //depot/maint-5.004/perl@922

4 files changed, 292 insertions, 4 deletions

diff --git a/MANIFEST b/MANIFEST
index 9f0962baa4..6dc628701a 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -16,6 +16,7 @@ Makefile.SH		A script that generates Makefile
 Porting/Contract	Guidelines for creating patches to Perl
 Porting/Glossary	Glossary of config.sh variables
 Porting/makerel		Release making utility
+Porting/patching.pod	How to report changes made to Perl
 Porting/patchls		Flexible patch file listing utility
 Porting/pumpkin.pod	Guidelines and hints for Perl maintainers
 README			The Instructions
diff --git a/Porting/makerel b/Porting/makerel
index f719a5e936..d6582edba1 100644
--- a/Porting/makerel
+++ b/Porting/makerel
@@ -21,9 +21,15 @@ $patchlevel_h = `grep '#define ' patchlevel.h`;
 print $patchlevel_h;
 $patchlevel = $1 if $patchlevel_h =~ /PATCHLEVEL\s+(\d+)/;
 $subversion = $1 if $patchlevel_h =~ /SUBVERSION\s+(\d+)/;
-die "Unable to parse patchlevel.h" unless $subversion > 0;
+die "Unable to parse patchlevel.h" unless $subversion >= 0;
 $vers = sprintf("5.%03d", $patchlevel);
-$vers.= sprintf( "_%02d", $subversion) if $subversion;
+$vms_vers = sprintf("5_%03d", $patchlevel);
+if ($subversion) {
+    $vers.= sprintf( "_%02d", $subversion);
+    $vms_vers.= sprintf( "%02d", $subversion);
+} else {
+    $vms_vers.= "  ";
+}
 
 $perl = "perl$vers";
 $reldir = "$relroot/$perl";
@@ -47,6 +53,10 @@ die "Aborted.\n" if @$missentry or @$missfile;
 print "\n";
 
 
+print "Updating VMS version specific files with $vms_vers...\n";
+system("perl -pi -e 's/^\QPERL_VERSION = \E\d\_\d+(\s*\#)/PERL_VERSION = $vms_vers$1/' vms/descrip.mms");
+
+
 print "Setting file permissions...\n";
 system("find . -type f -print     | xargs chmod -w");
 system("find . -type d -print     | xargs chmod g-s");
@@ -78,7 +88,7 @@ print "\n";
 
 
 print "Creating $reldir release directory...\n";
-die "$reldir release directory already exists\n"   if -e "../$perl";
+die "$reldir release directory already exists\n"   if -e "../$reldir";
 die "$reldir.tar.gz release file already exists\n" if -e "../$reldir.tar.gz";
 mkdir($reldir, 0755) or die "mkdir $reldir: $!\n";
 print "\n";
diff --git a/Porting/patching.pod b/Porting/patching.pod
new file mode 100644
index 0000000000..b2a86b6f34
--- /dev/null
+++ b/Porting/patching.pod
@@ -0,0 +1,275 @@
+=head1 Name
+
+patching.pod - Appropriate format for patches to the perl source tree
+
+=head2re to get this document
+
+The latest version of this document is available from
+     http://www.tdrenterprises.com/perl/perlpatch.html
+
+=head2 How to contribute to this document
+
+You may mail corrections, additions, and suggestions to me
+at dgris@tdrenterprises.com but the preferred method would be
+to follow the instructions set forth in this document and 
+submit a patch 8-).
+
+=head1 Description
+
+=head2 Why this document exists
+
+As an open source project Perl relies on patches and contributions from
+its users to continue functioning properly and to root out the inevitable
+bugs.  But, some users are unsure as to the I<right> way to prepare a patch
+and end up submitting seriously malformed patches.  This makes it very
+difficult for the current maintainer to integrate said patches into their
+distribution.  This document sets out usage guidelines for patches in an
+attempt to make everybody's life easier.
+
+=head2 Common problems
+
+The most common problems appear to be patches being mangled by certain
+mailers (I won't name names, but most of these seem to be originating on
+boxes running a certain popular commercial operating system). Other problems
+include patches not rooted in the appropriate place in the directory structure,
+and patches not produced using standard utilities (such as diff).
+
+=head1 Proper Patch Guidelines
+
+=head2 How to prepare your patch
+
+=over 4
+
+=item Creating your patch
+
+First, back up the original files.  This can't be stressed enough,
+back everything up _first_.
+
+Also, please create patches against a clean distribution of the perl source.
+This insures that everyone else can apply your patch without clobbering their
+source tree.
+
+=item diff
+
+While individual tastes vary (and are not the point here) patches should
+be created using either C<-u> or C<-c> arguments to diff.  These produce,
+respectively, unified diffs (where the changed line appears immediately next
+to the original) and context diffs (where several lines surrounding the changes
+are included).  See the manpage for diff for more details.
+
+Also, the preferred method for patching is -
+
+C<diff [C<-c> | C<-u>] E<lt>old-fileE<gt> E<lt>new-fileE<gt>>
+
+Note the order of files.
+
+Also, if your patch is to the core (rather than to a module) it
+is better to create it as a context diff as some machines have
+broken patch utilities that choke on unified diffs.
+
+=item Directories
+
+Patches should be generated from the source root directory, not from the
+directory that the patched file resides in.  This insures that the maintainer
+patches the proper file and avoids name collisions (especially common when trying
+to apply patches to files that appear in both $src_root/ext/* and $src_root/lib/*).
+It is better to diff the file in $src_root/ext than the file in $src_root/lib.
+
+=item Filenames
+
+The most usual convention when submitting patches for a single file is to make
+your changes to a copy of the file with the same name as the original.  Rename
+the original file in such a way that it is obvious what is being patched ($file~ or
+$file.old seem to be popular).
+
+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 C<-c> E<lt>old-dirE<gt> E<lt>new-dirE<gt>> to create all the patches
+at once.
+
+=back
+
+=head2 What to include in your patch
+
+=over 4
+
+=item Description of problem
+
+The first thing you should include is a description of the problem that
+the patch corrects.  If it is a code patch (rather than a documentation
+patch) you should also include a small test case that illustrates the
+bug.
+
+=item Direction for application
+
+You should include instructions on how to properly apply your patch.
+These should include the files affected, any shell scripts or commands
+that need to be run before or after application of the patch, and
+the command line necessary for application.
+
+=item If you have a code patch
+
+If you are submitting a code patch there are several other things that
+you need to do.
+
+=over 4
+
+=item Comments, Comments, Comments
+
+Be sure to adequately comment your code.  While commenting every
+line is unnecessary, anything that takes advantage of side effects of
+operators, that creates changes that will be felt outside of the
+function being patched, or that others may find confusing should
+be documented.  If you are going to err, it is better to err on the
+side of adding too many comments than too few.
+
+=item Style
+
+Please follow the indentation style and nesting style in use in the
+block of code that you are patching.
+
+=item Testsuite
+
+Also please include an addition to the regression tests to properly
+exercise your patch.
+
+=back
+
+=item Test your patch
+
+Apply your patch to a clean distribution, compile, and run the
+regression test suite (you did remember to add one for your
+patch, didn't you).
+
+=back
+
+=head2 An example patch creation
+
+This should work for most patches-
+
+      cp MANIFEST MANIFEST.old
+      emacs MANIFEST
+      (make changes)
+      cd ..
+      diff -c perl5.008_42/MANIFEST.old perl5.008_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
+      patch -p < mypatch
+      (should succeed)
+      diff perl5.008_42/MANIFEST perl5.008_42/MANIFEST.new
+      (should produce no output)
+
+=head2 Submitting your patch
+
+=over 4
+
+=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.
+
+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
+
+and post patch.uue with a note saying to unpack it using
+
+      perl -ne 'print unpack("u*",$_)' patch.uue > patch
+
+=item Subject lines for patches
+
+The subject line on your patch should read
+
+[PATCH]5.xxx_xx (Area) Description
+
+where the x's are replaced by the appropriate version number,
+area is a short keyword identifying what area of perl you are
+patching, and description is a very brief summary of the
+problem (don't forget this is an email header).
+
+Examples-
+
+[PATCH]5.004_04 (DOC) fix minor typos
+
+[PATCH]5.004_99 (CORE) New warning for foo() when frobbing
+
+[PATCH]5.005_42 (CONFIG) Added support for fribnatz 1.5
+
+=item Where to send your patch
+
+If your patch is for the perl core it should be sent perlbug@perl.org.
+If it is a patch to a module that you downloaded from CPAN you should
+submit your patch to that module's author.
+
+=back
+
+=head2 Applying a patch
+
+=over 4
+
+=item General notes on applying patches
+
+The following are some general notes on applying a patch
+to your perl distribution.
+
+=over 4
+
+=item patch C<-p>
+
+It is generally easier to apply patches with the C<-p> argument to
+patch.  This helps reconcile differing paths between the machine the
+patch was created on and the machine on which it is being applied.
+
+=item Cut and paste
+
+_Never_ cut and paste a patch into your editor.  This usually clobbers
+the tabs and confuses patch.
+
+=item Hand editing patches
+
+Avoid hand editing patches as this frequently screws up the whitespace
+in the patch and confuses the patch program.
+
+=back
+
+=back
+
+=head2 Final notes
+
+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 
+patches received.
+
+Also, just because you're not a brilliant coder doesn't mean that you can't
+contribute.  As valuable as code patches are there is always a need for better
+documentation (especially considering the general level of joy that most
+programmers feel when forced to sit down and write docs).  If all you do
+is patch the documentation you have still contributed more than the person
+who sent in an amazing new feature that noone can use because noone understands
+the code (what I'm getting at is that documentation is both the hardest part to
+do (because everyone hates doing it) and the most valuable).
+
+Mostly, when contributing patches, imagine that it is B<you> receiving hundreds
+of patches and that it is B<your> responsibility to integrate 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 1 May 1998 by Daniel Grisinger <dgris@tdrenterprises.com>
+
+=head1 Author and Copyright Information
+
+Copyright (c) 1998 Daniel Grisinger
+
+Adapted from a posting to perl5-porters by Tim Bunce (Tim.Bunce@ig.co.uk).
+
+I'd like to thank the perl5-porters for their suggestions.
+
+
+
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 20e496c75b..abe6a9f61a 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -863,7 +863,9 @@ is just like
 except that it's more efficient, more concise, keeps track of the
 current filename for error messages, and searches all the B<-I>
 libraries if the file isn't in the current directory (see also the @INC
-array in L<perlvar/Predefined Names>).  It's the same, however, in that it does
+array in L<perlvar/Predefined Names>).  It is also different in how
+code evaluated with C<do FILENAME> doesn't see lexicals in the enclosing
+scope like C<eval STRING> does.  It's the same, however, in that it does
 reparse the file every time you call it, so you probably don't want to
 do this inside a loop.