diff options
author | Tim Bunce <TimBunce@ig.ac.uk> | 1998-05-11 20:58:58 +0000 |
---|---|---|
committer | Tim Bunce <TimBunce@ig.ac.uk> | 1998-05-11 20:58:58 +0000 |
commit | 4bb840b5d205f16d8439fd3a413e362307c5a627 (patch) | |
tree | 7687fb05ed2c01be21dff3a7ec26005dbe2217fe | |
parent | 22a0dce32711e1a38e1f711e2466350ea6afdc06 (diff) | |
download | perl-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-- | MANIFEST | 1 | ||||
-rw-r--r-- | Porting/makerel | 16 | ||||
-rw-r--r-- | Porting/patching.pod | 275 | ||||
-rw-r--r-- | pod/perlfunc.pod | 4 |
4 files changed, 292 insertions, 4 deletions
@@ -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. |