From: Rafael Garcia-Suarez Date: Tue, 6 Jan 2009 08:44:55 +0000 (+0100) Subject: Delete the largely obsolete Porting/patching.pod X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=a44f43ac9f3e64cf7616266decab7e6aa6a22a56;p=p5sagit%2Fp5-mst-13.2.git Delete the largely obsolete Porting/patching.pod (but move some good advice in there to the perlrepository man page) --- diff --git a/MANIFEST b/MANIFEST index 579ad72..aa38aab 100644 --- a/MANIFEST +++ b/MANIFEST @@ -3530,7 +3530,6 @@ Porting/makerel Release making utility Porting/manicheck Check against MANIFEST Porting/p4d2p Generate patch from p4 diff Porting/p4genpatch Generate patch from p4 change in repository (obsoletes p4desc) -Porting/patching.pod How to report changes made to Perl Porting/patchls Flexible patch file listing utility Porting/podtidy Reformat pod using Pod::Tidy Porting/pumpkin.pod Guidelines and hints for Perl maintainers diff --git a/Porting/patching.pod b/Porting/patching.pod deleted file mode 100644 index 0b9e484..0000000 --- a/Porting/patching.pod +++ /dev/null @@ -1,418 +0,0 @@ -=head1 Name - -patching.pod - Appropriate format for patches to the perl source tree - -=head2 How to contribute to this document - -You may mail corrections, additions, and suggestions by following the -instructions set forth in this document and submitting a patch :). - -=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 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 What to patch - -Generally speaking you should patch the latest development release -of perl. The maintainers of the individual branches will see to it -that patches are picked up and applied as appropriate. - -=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 ensures 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. - -When GNU diff is available, the pumpkins would prefer you use C<-u -p> -(--unified --show-c-function) as arguments for optimal control. The -examples below will only use -u. - -The preferred method for creating a unified diff suitable for feeding -to the patch program is: - - diff -u old-file new-file > patch-file - -Note the order of files. See below for how to create a patch from -two directory trees. - -If your patch is for wider consumption, it may be better to create it as -a context diff as some machines have broken patch utilities that choke on -unified diffs. A context diff is made using C rather than -C. - -GNU diff has many desirable features not provided by most vendor-supplied -diffs. Some examples using GNU diff: - - # generate a patch for a newly added file - % diff -u /dev/null new/file - - # generate a patch to remove a file (patch > v2.4 will remove it cleanly) - % diff -u old/goner /dev/null - - # get additions, deletions along with everything else, recursively - % diff -ruN olddir newdir - - # ignore whitespace - % diff -bu a/file b/file - - # show function name in every hunk (safer, more informative) - % diff -u -p old/file new/file - % diff -u -F '^[_a-zA-Z0-9]+ *(' old/file new/file - - # show sub name in perl files and modules - % diff -u -F '^sub' old/file.pm new/file.pm - - # show header in doc patches - % diff -u -F '^=head' old/file.pod new/file.pod - -=item Derived Files - -Many files in the distribution are derivative--avoid patching them. -Patch the originals instead. Most utilities (like perldoc) are in -this category, i.e. patch utils/perldoc.PL rather than utils/perldoc. -Similarly, don't create patches for files under $src_root/ext from -their copies found in $install_root/lib. If you are unsure about the -proper location of a file that may have gotten copied while building -the source distribution, consult the C. - -=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.dist 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 to create all the patches at once. - -=item Directories - -IMPORTANT: Patches should be generated from the source root directory, not -from the directory that the patched file resides in. This ensures that the -maintainer patches the proper file. - -For larger patches that are dealing with multiple files or -directories, Johan Vromans has written a powerful utility: makepatch. -See the JV directory on CPAN for the current version. If you have this -program available, it is recommended to create a duplicate of the perl -directory tree against which you are intending to provide a patch and -let makepatch figure out all the changes you made to your copy of the -sources. As perl comes with a MANIFEST file, you need not delete -object files and other derivative files from the two directory trees, -makepatch is smart about them. - -Say, you have created a directory perl-5.7.1@8685/ for the perl you -are taking as the base and a directory perl-5.7.1@8685-withfoo/ where -you have your changes, you would run makepatch as follows: - - makepatch -oldman perl-5.7.1@8685/MANIFEST \ - -newman perl-5.7.1@8685-withfoo/MANIFEST \ - -diff "diff -u" \ - perl-5.7.1@8685 perl-5.7.1@8685-withfoo - -=item Binary Files - -Since the patch(1) utility cannot deal with binary files, it's important -that you either avoid the use of binary files in your patch, generate the -files dynamically, or that you encode any binary files using the -F utility. - -Assuming you needed to include a gzip-encoded file for a module's test -suite, you might do this as follows using the F utility: - - $ perl uupacktool.pl -v -p -D lib/Some/Module/t/src/t.gz - Writing lib/Some/Module/t/src/t.gz into lib/Some/Module/t/src/t.gz.packed - -This will replace the C file with an encoded counterpart. During -C, before any tests are run, perl's Makefile will restore all -the C<.packed> files mentioned in the MANIFEST to their original name. -This means that the test suite does not need to be aware of this packing -scheme and will not need to be altered. - -=item Try it yourself - -Just to make sure your patch "works", be sure to apply it to the Perl -distribution, rebuild everything, and make sure the testsuite runs -without incident. - -=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 Directions 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 - -In general, please follow the particular style of the code you are patching. - -In particular, follow these general guidelines for patching Perl sources: - - 8-wide tabs (no exceptions!) - 4-wide indents for code, 2-wide indents for nested CPP #defines - try hard not to exceed 79-columns - ANSI C prototypes - uncuddled elses and "K&R" style for indenting control constructs - no C++ style (//) comments, most C compilers will choke on them - mark places that need to be revisited with XXX (and revisit often!) - opening brace lines up with "if" when conditional spans multiple - lines; should be at end-of-line otherwise - in function definitions, name starts in column 0 (return value is on - previous line) - single space after keywords that are followed by parens, no space - between function name and following paren - avoid assignments in conditionals, but if they're unavoidable, use - extra paren, e.g. "if (a && (b = c)) ..." - "return foo;" rather than "return(foo);" - "if (!foo) ..." rather than "if (foo == FALSE) ..." etc. - - -=item Testsuite - -When submitting a patch you should make every effort to also include -an addition to perl's regression tests to properly exercise your -patch. Your testsuite additions should generally follow these -guidelines (courtesy of Gurusamy Sarathy ): - - Know what you're testing. Read the docs, and the source. - Tend to fail, not succeed. - Interpret results strictly. - Use unrelated features (this will flush out bizarre interactions). - Use non-standard idioms (otherwise you are not testing TIMTOWTDI). - Avoid using hardcoded test numbers whenever possible (the - EXPECTED/GOT found in t/op/tie.t is much more maintainable, - and gives better failure reports). - Give meaningful error messages when a test fails. - Avoid using qx// and system() unless you are testing for them. If you - do use them, make sure that you cover _all_ perl platforms. - Unlink any temporary files you create. - Promote unforeseen warnings to errors with $SIG{__WARN__}. - Be sure to use the libraries and modules shipped with the version - being tested, not those that were already installed. - Add comments to the code explaining what you are testing for. - Make updating the '1..42' string unnecessary. Or make sure that - you update it. - Test _all_ behaviors of a given operator, library, or function: - - All optional arguments - - Return values in various contexts (boolean, scalar, list, lvalue) - - Use both global and lexical variables - - Don't forget the exceptional, pathological cases. - -=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.7.42/MANIFEST.old perl5.7.42/MANIFEST > mypatch - (testing the patch:) - mv perl5.7.42/MANIFEST perl5.7.42/MANIFEST.new - cp perl5.7.42/MANIFEST.old perl5.7.42/MANIFEST - patch -p < mypatch - (should succeed) - diff perl5.7.42/MANIFEST perl5.7.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. This leaves the patch essentially worthless -to the maintainers. - -Unfortunately many mailers word wrap the main text of messages, but -luckily you can usually send your patches as email attachments without -them getting "helpfully" word wrapped. - -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.x.x AREA] Description - -where the x's are replaced by the appropriate version number. -The description should be a very brief but accurate summary of the -problem (don't forget this is an email header). - -Examples: - - [PATCH 5.6.4 DOC] fix minor typos - - [PATCH 5.7.9 CORE] New warning for foo() when frobbing - - [PATCH 5.7.16 CONFIG] Added support for fribnatz 1.5 - -The name of the file being patched makes for a poor subject line if -no other descriptive text accompanies it. - -=item Where to send your patch - -If your patch is for a specific bug in the Perl core, it should be sent -using the perlbug utility. Don't forget to describe the problem and the -fix adequately. - -If it is a patch to a module that you downloaded from CPAN you should -submit your patch to that module's author. - -If your patch addresses one of the items described in perltodo.pod, -please discuss your approach B you make the patch at -. Be sure to browse the archives of past -discussions (see perltodo.pod for archive locations). - -=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 N> argument to -patch (where N is the number of path components to skip in the files -found in the headers). This helps reconcile differing paths between -the machine the patch was created on and the machine on which it is -being applied. - -Be sure to use the Larry Wall version of patch. Some Operating Systems -(HP-UX amongst those) have a patch command that does something completely -different. The correct version of patch will show Larry's name several -times when invoked as patch --version. - -=item Cut and paste - -B 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 almost always screws up the line -numbers and offsets in the patch, making it useless. - -=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 no one can use because no one 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 receiving -hundreds of patches and that it is B 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 Author and Copyright Information - -Copyright (c) 1998-2002 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/perlrepository.pod b/pod/perlrepository.pod index 5b9069c..970d77c 100644 --- a/pod/perlrepository.pod +++ b/pod/perlrepository.pod @@ -238,6 +238,11 @@ that you're on the I branch, and your repository is up to date: % git checkout blead % git pull +(It's preferable to patch against the latest blead version, since patches +are usually integrated from blead to the maintainance branches. This +does not apply, obviously, in the rare case where your patch is specific +to a maintaince release.) + Now that we have everything up to date, we need to create a temporary new branch for these changes and switch into it: @@ -305,6 +310,115 @@ If you want to delete your temporary branch, you may do so with: % git branch -D orange Deleted branch orange. +=head2 A note on derived files + +Be aware that many files in the distribution are derivative--avoid +patching them, because git won't see the changes to them, and the +build process will overwrite them. +Patch the originals instead. Most utilities (like perldoc) are in +this category, i.e. patch utils/perldoc.PL rather than utils/perldoc. +Similarly, don't create patches for files under $src_root/ext from +their copies found in $install_root/lib. If you are unsure about the +proper location of a file that may have gotten copied while building +the source distribution, consult the C. + +=head2 A note on binary files + +Since the patch(1) utility cannot deal with binary files, it's important +that you either avoid the use of binary files in your patch, generate the +files dynamically, or that you encode any binary files using the +F utility. + +Assuming you needed to include a gzip-encoded file for a module's test +suite, you might do this as follows using the F utility: + + $ perl uupacktool.pl -v -p -D lib/Some/Module/t/src/t.gz + Writing lib/Some/Module/t/src/t.gz into lib/Some/Module/t/src/t.gz.packed + +This will replace the C file with an encoded counterpart. During +C, before any tests are run, perl's Makefile will restore all +the C<.packed> files mentioned in the MANIFEST to their original name. +This means that the test suite does not need to be aware of this packing +scheme and will not need to be altered. + +=head2 Getting your patch accepted + +The first thing you should include with your patch 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 (a patch to an existing test file is preferred). + +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 + +In general, please follow the particular style of the code you are patching. + +In particular, follow these general guidelines for patching Perl sources: + + 8-wide tabs (no exceptions!) + 4-wide indents for code, 2-wide indents for nested CPP #defines + try hard not to exceed 79-columns + ANSI C prototypes + uncuddled elses and "K&R" style for indenting control constructs + no C++ style (//) comments + mark places that need to be revisited with XXX (and revisit often!) + opening brace lines up with "if" when conditional spans multiple + lines; should be at end-of-line otherwise + in function definitions, name starts in column 0 (return value is on + previous line) + single space after keywords that are followed by parens, no space + between function name and following paren + avoid assignments in conditionals, but if they're unavoidable, use + extra paren, e.g. "if (a && (b = c)) ..." + "return foo;" rather than "return(foo);" + "if (!foo) ..." rather than "if (foo == FALSE) ..." etc. + +=item Testsuite + +When submitting a patch you should make every effort to also include +an addition to perl's regression tests to properly exercise your +patch. Your testsuite additions should generally follow these +guidelines (courtesy of Gurusamy Sarathy ): + + Know what you're testing. Read the docs, and the source. + Tend to fail, not succeed. + Interpret results strictly. + Use unrelated features (this will flush out bizarre interactions). + Use non-standard idioms (otherwise you are not testing TIMTOWTDI). + Avoid using hardcoded test numbers whenever possible (the + EXPECTED/GOT found in t/op/tie.t is much more maintainable, + and gives better failure reports). + Give meaningful error messages when a test fails. + Avoid using qx// and system() unless you are testing for them. If you + do use them, make sure that you cover _all_ perl platforms. + Unlink any temporary files you create. + Promote unforeseen warnings to errors with $SIG{__WARN__}. + Be sure to use the libraries and modules shipped with the version + being tested, not those that were already installed. + Add comments to the code explaining what you are testing for. + Make updating the '1..42' string unnecessary. Or make sure that + you update it. + Test _all_ behaviors of a given operator, library, or function: + - All optional arguments + - Return values in various contexts (boolean, scalar, list, lvalue) + - Use both global and lexical variables + - Don't forget the exceptional, pathological cases. + +=back + =head1 ACCEPTING A PATCH If you have received a patch file generated using the above section,