[win32] merge changes#922,944,949,965,970 from maintbranch

p4raw-link: @970 on //depot/maint-5.004/perl: 5362f8886d6c3fb908c863d910b1a158479419e2
p4raw-link: @965 on //depot/maint-5.004/perl: 8472ac73d6d802946d766b5459d2d9c334889a3f
p4raw-link: @949 on //depot/maint-5.004/perl: 4b161ae29769b4a3eb304314bbbfe5969417c8ec
p4raw-link: @944 on //depot/maint-5.004/perl: fa366f5fbba3f21113f9677105663454a3e0b678
p4raw-link: @922 on //depot/maint-5.004/perl: 68daf0ababdc0e913335a90c4361b792b2715301

p4raw-id: //depot/win32/perl@978

1 files changed, 275 insertions, 0 deletions

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.
+
+
+