summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTim Bunce <TimBunce@ig.ac.uk>1998-05-11 20:58:58 +0000
committerTim Bunce <TimBunce@ig.ac.uk>1998-05-11 20:58:58 +0000
commit4bb840b5d205f16d8439fd3a413e362307c5a627 (patch)
tree7687fb05ed2c01be21dff3a7ec26005dbe2217fe
parent22a0dce32711e1a38e1f711e2466350ea6afdc06 (diff)
downloadperl-4bb840b5d205f16d8439fd3a413e362307c5a627.tar.gz
[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
-rw-r--r--MANIFEST1
-rw-r--r--Porting/makerel16
-rw-r--r--Porting/patching.pod275
-rw-r--r--pod/perlfunc.pod4
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.