forked from schacon/perl
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[difference between patch application from Change 913 and Change 922]
------ 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: 91b1e15 p4raw-id: //depot/maint-5.004/perl@922
- Loading branch information
Tim Bunce
authored and
Tim Bunce
committed
May 11, 1998
1 parent
67c02ff
commit 68daf0a
Showing
4 changed files
with
292 additions
and
4 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. | ||
|
||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters