+=for comment
+Consistent formatting of this file is achieved with:
+ perl ./Porting/podtidy pod/perlrepository.pod
+
=head1 NAME
perlrepository - Using the Perl source repository
and that there were further changes in the working directory not yet
staged. It also shows that there was an untracked file in the working
directory, and as you can see shows how to change all of this. It also
-shows that there is one commit on the working branch C<blead> which
-has not been pushed to the C<origin> remote yet. B<NOTE>: that this
-output is also what you see as a template if you do not provide a
-message to C<git commit>.
+shows that there is one commit on the working branch C<blead> which has
+not been pushed to the C<origin> remote yet. B<NOTE>: that this output
+is also what you see as a template if you do not provide a message to
+C<git commit>.
Assuming we commit all the mentioned changes above:
% git checkout blead
% git pull
-(It's preferable to patch against the latest blead version, since patches
-are usually integrated from blead to the maintenance branches. This
-does not apply, obviously, in the rare case where your patch is specific
-to a maintaince release.)
+(It's preferable to patch against the latest blead version, since
+patches are usually integrated from blead to the maintenance 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:
=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<MANIFEST>.
+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<MANIFEST>.
=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<uupacktool.pl> utility.
+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<uupacktool.pl> 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<uupacktool.pl> utility:
Writing lib/Some/Module/t/src/t.gz into lib/Some/Module/t/src/t.gz.packed
This will replace the C<t.gz> file with an encoded counterpart. During
-C<make test>, 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.
+C<make test>, 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).
+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.
=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
+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.
+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 general, please follow the particular style of the code you are
+patching.
-In particular, follow these general guidelines for patching Perl sources:
+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
=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 <gsar@activestate.com>):
+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 <gsar@activestate.com>):
Know what you're testing. Read the docs, and the source.
Tend to fail, not succeed.
to remove all ignored untracked files, such as build and test
byproduct, but leave any manually created files alone.
-If you only want to cancel some uncommitted edits, you can use
-C<git checkout> and give it a list of files to be reverted.
+If you only want to cancel some uncommitted edits, you can use C<git
+checkout> and give it a list of files to be reverted.
If you want to cancel one or several commits, you can use C<git reset>.
% git checkout --track -b maint-5.005 origin/maint-5.005
-This creates a local branch named C<maint-5.005>, which tracks the remote
-branch C<origin/maint-5.005>. Then you can pull, commit, merge and push as
-before.
+This creates a local branch named C<maint-5.005>, which tracks the
+remote branch C<origin/maint-5.005>. Then you can pull, commit, merge
+and push as before.
You can also cherry-pick commits from blead and another branch, by
-using the C<git cherry-pick> command. It is recommended to use the B<-x>
-option to C<git cherry-pick> in order to record the SHA1 of the original
-commit in the new commit message.
+using the C<git cherry-pick> command. It is recommended to use the
+B<-x> option to C<git cherry-pick> in order to record the SHA1 of the
+original commit in the new commit message.
=head1 SEE ALSO
The git documentation, accessible via C<git help command>.
+
projects / p5sagit/p5-mst-13.2.git / commitdiff