Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1076 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man1/perlgit.1 b/upstream/mageia-cauldron/man1/perlgit.1
new file mode 100644
index 00000000..70753920
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlgit.1
@@ -0,0 +1,1076 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLGIT 1"
+.TH PERLGIT 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH NAME
+perlgit \- Detailed information about git and the Perl repository
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document provides details on using git to develop Perl. If you are
+just interested in working on a quick patch, see perlhack first.
+This document is intended for people who are regular contributors to
+Perl, including those with write access to the git repository.
+.SH "CLONING THE REPOSITORY"
+.IX Header "CLONING THE REPOSITORY"
+All of Perl's source code is kept centrally in a Git repository at
+\&\fIgithub.com\fR.
+.PP
+You can make a read-only clone of the repository by running:
+.PP
+.Vb 1
+\&  % git clone git@github.com:Perl/perl5.git perl
+.Ve
+.PP
+If you cannot use that for firewall reasons, you can also clone via http:
+.PP
+.Vb 1
+\&  % git clone https://github.com/Perl/perl5.git perl
+.Ve
+.SH "WORKING WITH THE REPOSITORY"
+.IX Header "WORKING WITH THE REPOSITORY"
+Once you have changed into the repository directory, you can inspect
+it. After a clone the repository will contain a single local branch,
+which will be the current branch as well, as indicated by the asterisk.
+.PP
+.Vb 2
+\&  % git branch
+\&  * blead
+.Ve
+.PP
+Using the \-a switch to \f(CW\*(C`branch\*(C'\fR will also show the remote tracking
+branches in the repository:
+.PP
+.Vb 5
+\&  % git branch \-a
+\&  * blead
+\&    origin/HEAD
+\&    origin/blead
+\&  ...
+.Ve
+.PP
+The branches that begin with "origin" correspond to the "git remote"
+that you cloned from (which is named "origin"). Each branch on the
+remote will be exactly tracked by these branches. You should NEVER do
+work on these remote tracking branches. You only ever do work in a
+local branch. Local branches can be configured to automerge (on pull)
+from a designated remote tracking branch. This is the case with the
+default branch \f(CW\*(C`blead\*(C'\fR which will be configured to merge from the
+remote tracking branch \f(CW\*(C`origin/blead\*(C'\fR.
+.PP
+You can see recent commits:
+.PP
+.Vb 1
+\&  % git log
+.Ve
+.PP
+And pull new changes from the repository, and update your local
+repository (must be clean first)
+.PP
+.Vb 1
+\&  % git pull
+.Ve
+.PP
+Assuming we are on the branch \f(CW\*(C`blead\*(C'\fR immediately after a pull, this
+command would be more or less equivalent to:
+.PP
+.Vb 2
+\&  % git fetch
+\&  % git merge origin/blead
+.Ve
+.PP
+In fact if you want to update your local repository without touching
+your working directory you do:
+.PP
+.Vb 1
+\&  % git fetch
+.Ve
+.PP
+And if you want to update your remote-tracking branches for all defined
+remotes simultaneously you can do
+.PP
+.Vb 1
+\&  % git remote update
+.Ve
+.PP
+Neither of these last two commands will update your working directory,
+however both will update the remote-tracking branches in your
+repository.
+.PP
+To make a local branch of a remote branch:
+.PP
+.Vb 1
+\&  % git checkout \-b maint\-5.10 origin/maint\-5.10
+.Ve
+.PP
+To switch back to blead:
+.PP
+.Vb 1
+\&  % git checkout blead
+.Ve
+.SS "Finding out your status"
+.IX Subsection "Finding out your status"
+The most common git command you will use will probably be
+.PP
+.Vb 1
+\&  % git status
+.Ve
+.PP
+This command will produce as output a description of the current state
+of the repository, including modified files and unignored untracked
+files, and in addition it will show things like what files have been
+staged for the next commit, and usually some useful information about
+how to change things. For instance the following:
+.PP
+.Vb 3
+\& % git status
+\& On branch blead
+\& Your branch is ahead of \*(Aqorigin/blead\*(Aq by 1 commit.
+\&
+\& Changes to be committed:
+\&   (use "git reset HEAD <file>..." to unstage)
+\&
+\&       modified:   pod/perlgit.pod
+\&
+\& Changes not staged for commit:
+\&   (use "git add <file>..." to update what will be committed)
+\&   (use "git checkout \-\- <file>..." to discard changes in working
+\&                                                              directory)
+\&
+\&       modified:   pod/perlgit.pod
+\&
+\& Untracked files:
+\&   (use "git add <file>..." to include in what will be committed)
+\&
+\&       deliberate.untracked
+.Ve
+.PP
+This shows that there were changes to this document staged for commit,
+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 \f(CW\*(C`blead\*(C'\fR which has
+not been pushed to the \f(CW\*(C`origin\*(C'\fR remote yet. \fBNOTE\fR: This output
+is also what you see as a template if you do not provide a message to
+\&\f(CW\*(C`git commit\*(C'\fR.
+.SS "Patch workflow"
+.IX Subsection "Patch workflow"
+First, please read perlhack for details on hacking the Perl core.
+That document covers many details on how to create a good patch.
+.PP
+If you already have a Perl repository, you should ensure that you're on
+the \fIblead\fR branch, and your repository is up to date:
+.PP
+.Vb 2
+\&  % git checkout blead
+\&  % git pull
+.Ve
+.PP
+It's preferable to patch against the latest blead version, since this
+is where new development occurs for all changes other than critical bug
+fixes. Critical bug fix patches should be made against the relevant
+maint branches, or should be submitted with a note indicating all the
+branches where the fix should be applied.
+.PP
+Now that we have everything up to date, we need to create a temporary
+new branch for these changes and switch into it:
+.PP
+.Vb 1
+\&  % git checkout \-b orange
+.Ve
+.PP
+which is the short form of
+.PP
+.Vb 2
+\&  % git branch orange
+\&  % git checkout orange
+.Ve
+.PP
+Creating a topic branch makes it easier for the maintainers to rebase
+or merge back into the master blead for a more linear history. If you
+don't work on a topic branch the maintainer has to manually cherry pick
+your changes onto blead before they can be applied.
+.PP
+That'll get you scolded on perl5\-porters, so don't do that. Be Awesome.
+.PP
+Then make your changes. For example, if Leon Brocard changes his name
+to Orange Brocard, we should change his name in the AUTHORS file:
+.PP
+.Vb 1
+\&  % perl \-pi \-e \*(Aqs{Leon Brocard}{Orange Brocard}\*(Aq AUTHORS
+.Ve
+.PP
+You can see what files are changed:
+.PP
+.Vb 4
+\&  % git status
+\&  On branch orange
+\&  Changes to be committed:
+\&    (use "git reset HEAD <file>..." to unstage)
+\&
+\&     modified:   AUTHORS
+.Ve
+.PP
+And you can see the changes:
+.PP
+.Vb 10
+\& % git diff
+\& diff \-\-git a/AUTHORS b/AUTHORS
+\& index 293dd70..722c93e 100644
+\& \-\-\- a/AUTHORS
+\& +++ b/AUTHORS
+\& @@ \-541,7 +541,7 @@    Lars Hecking              <lhecking@nmrc.ucc.ie>
+\&  Laszlo Molnar                  <laszlo.molnar@eth.ericsson.se>
+\&  Leif Huhn                      <leif@hale.dkstat.com>
+\&  Len Johnson                    <lenjay@ibm.net>
+\& \-Leon Brocard                   <acme@astray.com>
+\& +Orange Brocard                 <acme@astray.com>
+\&  Les Peters                     <lpeters@aol.net>
+\&  Lesley Binks                   <lesley.binks@gmail.com>
+\&  Lincoln D. Stein               <lstein@cshl.org>
+.Ve
+.PP
+Now commit your change locally:
+.PP
+.Vb 3
+\& % git commit \-a \-m \*(AqRename Leon Brocard to Orange Brocard\*(Aq
+\& Created commit 6196c1d: Rename Leon Brocard to Orange Brocard
+\&  1 files changed, 1 insertions(+), 1 deletions(\-)
+.Ve
+.PP
+The \f(CW\*(C`\-a\*(C'\fR option is used to include all files that git tracks that you
+have changed. If at this time, you only want to commit some of the
+files you have worked on, you can omit the \f(CW\*(C`\-a\*(C'\fR and use the command
+\&\f(CW\*(C`git\ add\ \fR\f(CIFILE\ ...\fR\f(CW\*(C'\fR before doing the commit. \f(CW\*(C`git\ add\ \-\-interactive\*(C'\fR allows you to even just commit portions of files
+instead of all the changes in them.
+.PP
+The \f(CW\*(C`\-m\*(C'\fR option is used to specify the commit message. If you omit it,
+git will open a text editor for you to compose the message
+interactively. This is useful when the changes are more complex than
+the sample given here, and, depending on the editor, to know that the
+first line of the commit message doesn't exceed the 50 character legal
+maximum. See "Commit message" in perlhack for more information about what
+makes a good commit message.
+.PP
+Once you've finished writing your commit message and exited your
+editor, git will write your change to disk and tell you something like
+this:
+.PP
+.Vb 2
+\& Created commit daf8e63: explain git status and stuff about remotes
+\&  1 files changed, 83 insertions(+), 3 deletions(\-)
+.Ve
+.PP
+If you re-run \f(CW\*(C`git status\*(C'\fR, you should see something like this:
+.PP
+.Vb 4
+\& % git status
+\& On branch orange
+\& Untracked files:
+\&   (use "git add <file>..." to include in what will be committed)
+\&
+\&       deliberate.untracked
+\&
+\& nothing added to commit but untracked files present (use "git add" to
+\&                                                                  track)
+.Ve
+.PP
+When in doubt, before you do anything else, check your status and read
+it carefully, many questions are answered directly by the git status
+output.
+.PP
+You can examine your last commit with:
+.PP
+.Vb 1
+\&  % git show HEAD
+.Ve
+.PP
+and if you are not happy with either the description or the patch
+itself you can fix it up by editing the files once more and then issue:
+.PP
+.Vb 1
+\&  % git commit \-a \-\-amend
+.Ve
+.PP
+Now, create a fork on GitHub to push your branch to, and add it as a
+remote if you haven't already, as described in the GitHub documentation
+at <https://help.github.com/en/articles/working\-with\-forks>:
+.PP
+.Vb 1
+\&  % git remote add fork git@github.com:MyUser/perl5.git
+.Ve
+.PP
+And push the branch to your fork:
+.PP
+.Vb 1
+\&  % git push \-u fork orange
+.Ve
+.PP
+You should now submit a Pull Request (PR) on GitHub from the new branch
+to blead. For more information, see the GitHub documentation at
+<https://help.github.com/en/articles/creating\-a\-pull\-request\-from\-a\-fork>.
+.PP
+You can also send patch files to
+perl5\-porters@perl.org <mailto:perl5-porters@perl.org> directly if the
+patch is not ready to be applied, but intended for discussion.
+.PP
+To create a patch file for all your local changes:
+.PP
+.Vb 2
+\&  % git format\-patch \-M blead..
+\&  0001\-Rename\-Leon\-Brocard\-to\-Orange\-Brocard.patch
+.Ve
+.PP
+Or for a lot of changes, e.g. from a topic branch:
+.PP
+.Vb 1
+\&  % git format\-patch \-\-stdout \-M blead.. > topic\-branch\-changes.patch
+.Ve
+.PP
+If you want to delete your temporary branch, you may do so with:
+.PP
+.Vb 6
+\& % git checkout blead
+\& % git branch \-d orange
+\& error: The branch \*(Aqorange\*(Aq is not an ancestor of your current HEAD.
+\& If you are sure you want to delete it, run \*(Aqgit branch \-D orange\*(Aq.
+\& % git branch \-D orange
+\& Deleted branch orange.
+.Ve
+.SS "A note on derived files"
+.IX Subsection "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
+\&\fIutils/perldoc.PL\fR rather than \fIutils/perldoc\fR. Similarly, don't
+create patches for files under \fR\f(CI$src_root\fR\fI/ext\fR from their copies found
+in \fI\fR\f(CI$install_root\fR\fI/lib\fR. If you are unsure about the proper location of
+a file that may have gotten copied while building the source
+distribution, consult the \fIMANIFEST\fR.
+.SS "Cleaning a working directory"
+.IX Subsection "Cleaning a working directory"
+The command \f(CW\*(C`git clean\*(C'\fR can with varying arguments be used as a
+replacement for \f(CW\*(C`make clean\*(C'\fR.
+.PP
+To reset your working directory to a pristine condition you can do:
+.PP
+.Vb 1
+\&  % git clean \-dxf
+.Ve
+.PP
+However, be aware this will delete ALL untracked content. You can use
+.PP
+.Vb 1
+\&  % git clean \-Xf
+.Ve
+.PP
+to remove all ignored untracked files, such as build and test
+byproduct, but leave any manually created files alone.
+.PP
+If you only want to cancel some uncommitted edits, you can use \f(CW\*(C`git
+checkout\*(C'\fR and give it a list of files to be reverted, or \f(CW\*(C`git checkout
+\&\-f\*(C'\fR to revert them all.
+.PP
+If you want to cancel one or several commits, you can use \f(CW\*(C`git reset\*(C'\fR.
+.SS Bisecting
+.IX Subsection "Bisecting"
+\&\f(CW\*(C`git\*(C'\fR provides a built-in way to determine which commit should be blamed
+for introducing a given bug. \f(CW\*(C`git bisect\*(C'\fR performs a binary search of
+history to locate the first failing commit. It is fast, powerful and
+flexible, but requires some setup and to automate the process an auxiliary
+shell script is needed.
+.PP
+The core provides a wrapper program, \fIPorting/bisect.pl\fR, which attempts to
+simplify as much as possible, making bisecting as simple as running a Perl
+one-liner. For example, if you want to know when this became an error:
+.PP
+.Vb 1
+\&    perl \-e \*(Aqmy $a := 2\*(Aq
+.Ve
+.PP
+you simply run this:
+.PP
+.Vb 1
+\&    .../Porting/bisect.pl \-e \*(Aqmy $a := 2;\*(Aq
+.Ve
+.PP
+Using \fIPorting/bisect.pl\fR, with one command (and no other files) it's easy to
+find out
+.IP \(bu 4
+Which commit caused this example code to break?
+.IP \(bu 4
+Which commit caused this example code to start working?
+.IP \(bu 4
+Which commit added the first file to match this regex?
+.IP \(bu 4
+Which commit removed the last file to match this regex?
+.PP
+usually without needing to know which versions of perl to use as start and
+end revisions, as \fIPorting/bisect.pl\fR automatically searches to find the
+earliest stable version for which the test case passes. Run
+\&\f(CW\*(C`Porting/bisect.pl \-\-help\*(C'\fR for the full documentation, including how to
+set the \f(CW\*(C`Configure\*(C'\fR and build time options.
+.PP
+If you require more flexibility than \fIPorting/bisect.pl\fR has to offer, you'll
+need to run \f(CW\*(C`git bisect\*(C'\fR yourself. It's most useful to use \f(CW\*(C`git bisect run\*(C'\fR
+to automate the building and testing of perl revisions. For this you'll need
+a shell script for \f(CW\*(C`git\*(C'\fR to call to test a particular revision. An example
+script is \fIPorting/bisect\-example.sh\fR, which you should copy \fBoutside\fR of
+the repository, as the bisect process will reset the state to a clean checkout
+as it runs. The instructions below assume that you copied it as \fI~/run\fR and
+then edited it as appropriate.
+.PP
+You first enter in bisect mode with:
+.PP
+.Vb 1
+\&  % git bisect start
+.Ve
+.PP
+For example, if the bug is present on \f(CW\*(C`HEAD\*(C'\fR but wasn't in 5.10.0,
+\&\f(CW\*(C`git\*(C'\fR will learn about this when you enter:
+.PP
+.Vb 3
+\&  % git bisect bad
+\&  % git bisect good perl\-5.10.0
+\&  Bisecting: 853 revisions left to test after this
+.Ve
+.PP
+This results in checking out the median commit between \f(CW\*(C`HEAD\*(C'\fR and
+\&\f(CW\*(C`perl\-5.10.0\*(C'\fR. You can then run the bisecting process with:
+.PP
+.Vb 1
+\&  % git bisect run ~/run
+.Ve
+.PP
+When the first bad commit is isolated, \f(CW\*(C`git bisect\*(C'\fR will tell you so:
+.PP
+.Vb 4
+\&  ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 is first bad commit
+\&  commit ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5
+\&  Author: Dave Mitchell <davem@fdisolutions.com>
+\&  Date:   Sat Feb 9 14:56:23 2008 +0000
+\&
+\&      [perl #49472] Attributes + Unknown Error
+\&      ...
+\&
+\&  bisect run success
+.Ve
+.PP
+You can peek into the bisecting process with \f(CW\*(C`git bisect log\*(C'\fR and
+\&\f(CW\*(C`git bisect visualize\*(C'\fR. \f(CW\*(C`git bisect reset\*(C'\fR will get you out of bisect
+mode.
+.PP
+Please note that the first \f(CW\*(C`good\*(C'\fR state must be an ancestor of the
+first \f(CW\*(C`bad\*(C'\fR state. If you want to search for the commit that \fIsolved\fR
+some bug, you have to negate your test case (i.e. exit with \f(CW1\fR if OK
+and \f(CW0\fR if not) and still mark the lower bound as \f(CW\*(C`good\*(C'\fR and the
+upper as \f(CW\*(C`bad\*(C'\fR. The "first bad commit" has then to be understood as
+the "first commit where the bug is solved".
+.PP
+\&\f(CW\*(C`git help bisect\*(C'\fR has much more information on how you can tweak your
+binary searches.
+.PP
+Following bisection you may wish to configure, build and test perl at
+commits identified by the bisection process.  Sometimes, particularly
+with older perls, \f(CW\*(C`make\*(C'\fR may fail during this process.  In this case
+you may be able to patch the source code at the older commit point.  To
+do so, please follow the suggestions provided in
+"Building perl at older commits" in perlhack.
+.SS "Topic branches and rewriting history"
+.IX Subsection "Topic branches and rewriting history"
+Individual committers should create topic branches under
+\&\fByourname\fR/\fBsome_descriptive_name\fR:
+.PP
+.Vb 4
+\&  % branch="$yourname/$some_descriptive_name"
+\&  % git checkout \-b $branch
+\&  ... do local edits, commits etc ...
+\&  % git push origin \-u $branch
+.Ve
+.PP
+Should you be stuck with an ancient version of git (prior to 1.7), then
+\&\f(CW\*(C`git push\*(C'\fR will not have the \f(CW\*(C`\-u\*(C'\fR switch, and you have to replace the
+last step with the following sequence:
+.PP
+.Vb 3
+\&  % git push origin $branch:refs/heads/$branch
+\&  % git config branch.$branch.remote origin
+\&  % git config branch.$branch.merge refs/heads/$branch
+.Ve
+.PP
+If you want to make changes to someone else's topic branch, you should
+check with its creator before making any change to it.
+.PP
+You
+might sometimes find that the original author has edited the branch's
+history. There are lots of good reasons for this. Sometimes, an author
+might simply be rebasing the branch onto a newer source point.
+Sometimes, an author might have found an error in an early commit which
+they wanted to fix before merging the branch to blead.
+.PP
+Currently the master repository is configured to forbid
+non-fast-forward merges. This means that the branches within can not be
+rebased and pushed as a single step.
+.PP
+The only way you will ever be allowed to rebase or modify the history
+of a pushed branch is to delete it and push it as a new branch under
+the same name. Please think carefully about doing this. It may be
+better to sequentially rename your branches so that it is easier for
+others working with you to cherry-pick their local changes onto the new
+version. (XXX: needs explanation).
+.PP
+If you want to rebase a personal topic branch, you will have to delete
+your existing topic branch and push as a new version of it. You can do
+this via the following formula (see the explanation about \f(CW\*(C`refspec\*(C'\fR's
+in the git push documentation for details) after you have rebased your
+branch:
+.PP
+.Vb 4
+\&  # first rebase
+\&  % git checkout $user/$topic
+\&  % git fetch
+\&  % git rebase origin/blead
+\&
+\&  # then "delete\-and\-push"
+\&  % git push origin :$user/$topic
+\&  % git push origin $user/$topic
+.Ve
+.PP
+\&\fBNOTE:\fR it is forbidden at the repository level to delete any of the
+"primary" branches. That is any branch matching
+\&\f(CW\*(C`m!^(blead|maint|perl)!\*(C'\fR. Any attempt to do so will result in git
+producing an error like this:
+.PP
+.Vb 7
+\&  % git push origin :blead
+\&  *** It is forbidden to delete blead/maint branches in this repository
+\&  error: hooks/update exited with error code 1
+\&  error: hook declined to update refs/heads/blead
+\&  To ssh://perl5.git.perl.org/perl
+\&   ! [remote rejected] blead (hook declined)
+\&   error: failed to push some refs to \*(Aqssh://perl5.git.perl.org/perl\*(Aq
+.Ve
+.PP
+As a matter of policy we do \fBnot\fR edit the history of the blead and
+maint\-* branches. If a typo (or worse) sneaks into a commit to blead or
+maint\-*, we'll fix it in another commit. The only types of updates
+allowed on these branches are "fast-forwards", where all history is
+preserved.
+.PP
+Annotated tags in the canonical perl.git repository will never be
+deleted or modified. Think long and hard about whether you want to push
+a local tag to perl.git before doing so. (Pushing simple tags is
+not allowed.)
+.SS Grafts
+.IX Subsection "Grafts"
+The perl history contains one mistake which was not caught in the
+conversion: a merge was recorded in the history between blead and
+maint\-5.10 where no merge actually occurred. Due to the nature of git,
+this is now impossible to fix in the public repository. You can remove
+this mis-merge locally by adding the following line to your
+\&\f(CW\*(C`.git/info/grafts\*(C'\fR file:
+.PP
+.Vb 1
+\& 296f12bbbbaa06de9be9d09d3dcf8f4528898a49 434946e0cb7a32589ed92d18008aaa1d88515930
+.Ve
+.PP
+It is particularly important to have this graft line if any bisecting
+is done in the area of the "merge" in question.
+.SH "WRITE ACCESS TO THE GIT REPOSITORY"
+.IX Header "WRITE ACCESS TO THE GIT REPOSITORY"
+Once you have write access, you will need to modify the URL for the
+origin remote to enable pushing. Edit \fI.git/config\fR with the
+\&\fBgit\-config\fR\|(1) command:
+.PP
+.Vb 1
+\&  % git config remote.origin.url git@github.com:Perl/perl5.git
+.Ve
+.PP
+You can also set up your user name and e\-mail address. Most people do
+this once globally in their \fI~/.gitconfig\fR by doing something like:
+.PP
+.Vb 2
+\&  % git config \-\-global user.name "Ævar Arnfjörð Bjarmason"
+\&  % git config \-\-global user.email avarab@gmail.com
+.Ve
+.PP
+However, if you'd like to override that just for perl,
+execute something like the following in \fIperl\fR:
+.PP
+.Vb 1
+\&  % git config user.email avar@cpan.org
+.Ve
+.PP
+It is also possible to keep \f(CW\*(C`origin\*(C'\fR as a git remote, and add a new
+remote for ssh access:
+.PP
+.Vb 1
+\&  % git remote add camel git@github.com:Perl/perl5.git
+.Ve
+.PP
+This allows you to update your local repository by pulling from
+\&\f(CW\*(C`origin\*(C'\fR, which is faster and doesn't require you to authenticate, and
+to push your changes back with the \f(CW\*(C`camel\*(C'\fR remote:
+.PP
+.Vb 2
+\&  % git fetch camel
+\&  % git push camel
+.Ve
+.PP
+The \f(CW\*(C`fetch\*(C'\fR command just updates the \f(CW\*(C`camel\*(C'\fR refs, as the objects
+themselves should have been fetched when pulling from \f(CW\*(C`origin\*(C'\fR.
+.SS "Working with Github pull requests"
+.IX Subsection "Working with Github pull requests"
+Pull requests typically originate from outside of the \f(CW\*(C`Perl/perl.git\*(C'\fR
+repository, so if you want to test or work with it locally a vanilla
+\&\f(CW\*(C`git fetch\*(C'\fR from the \f(CW\*(C`Perl/perl5.git\*(C'\fR repository won't fetch it.
+.PP
+However Github does provide a mechanism to fetch a pull request to a
+local branch.  They are available on Github remotes under \f(CW\*(C`pull/\*(C'\fR, so
+you can use \f(CW\*(C`git fetch pull/\fR\f(CIPRID\fR\f(CW/head:\fR\f(CIlocalname\fR\f(CW\*(C'\fR to make a
+local copy.  eg.  to fetch pull request 9999 to the local branch
+\&\f(CW\*(C`local\-branch\-name\*(C'\fR run:
+.PP
+.Vb 1
+\&  git fetch origin pull/9999/head:local\-branch\-name
+.Ve
+.PP
+and then:
+.PP
+.Vb 1
+\&  git checkout local\-branch\-name
+.Ve
+.PP
+Note: this branch is not rebased on \f(CW\*(C`blead\*(C'\fR, so instead of the
+checkout above, you might want:
+.PP
+.Vb 1
+\&  git rebase origin/blead local\-branch\-name
+.Ve
+.PP
+which rebases \f(CW\*(C`local\-branch\-name\*(C'\fR on \f(CW\*(C`blead\*(C'\fR, and checks it out.
+.PP
+Alternatively you can configure the remote to fetch all pull requests
+as remote-tracking branches.  To do this edit the remote in
+\&\fI.git/config\fR, for example if your github remote is \f(CW\*(C`origin\*(C'\fR you'd
+have:
+.PP
+.Vb 3
+\&  [remote "origin"]
+\&          url = git@github.com:/Perl/perl5.git
+\&          fetch = +refs/heads/*:refs/remotes/origin/*
+.Ve
+.PP
+Add a line to map the remote pull request branches to remote-tracking
+branches:
+.PP
+.Vb 4
+\&  [remote "origin"]
+\&          url = git@github.com:/Perl/perl5.git
+\&          fetch = +refs/heads/*:refs/remotes/origin/*
+\&          fetch = +refs/pull/*/head:refs/remotes/origin/pull/*
+.Ve
+.PP
+and then do a fetch as normal:
+.PP
+.Vb 1
+\&  git fetch origin
+.Ve
+.PP
+This will create a remote-tracking branch for every pull request, including
+closed requests.
+.PP
+To remove those remote-tracking branches, remove the line added above
+and prune:
+.PP
+.Vb 1
+\&  git fetch \-p origin # or git remote prune origin
+.Ve
+.SS "Accepting a patch"
+.IX Subsection "Accepting a patch"
+If you have received a patch file generated using the above section,
+you should try out the patch.
+.PP
+First we need to create a temporary new branch for these changes and
+switch into it:
+.PP
+.Vb 1
+\& % git checkout \-b experimental
+.Ve
+.PP
+Patches that were formatted by \f(CW\*(C`git format\-patch\*(C'\fR are applied with
+\&\f(CW\*(C`git am\*(C'\fR:
+.PP
+.Vb 2
+\& % git am 0001\-Rename\-Leon\-Brocard\-to\-Orange\-Brocard.patch
+\& Applying Rename Leon Brocard to Orange Brocard
+.Ve
+.PP
+Note that some UNIX mail systems can mess with text attachments containing
+\&'From '. This will fix them up:
+.PP
+.Vb 2
+\& % perl \-pi \-e\*(Aqs/^>From /From /\*(Aq \e
+\&                        0001\-Rename\-Leon\-Brocard\-to\-Orange\-Brocard.patch
+.Ve
+.PP
+If just a raw diff is provided, it is also possible use this two-step
+process:
+.PP
+.Vb 3
+\& % git apply bugfix.diff
+\& % git commit \-a \-m "Some fixing" \e
+\&                            \-\-author="That Guy <that.guy@internets.com>"
+.Ve
+.PP
+Now we can inspect the change:
+.PP
+.Vb 4
+\& % git show HEAD
+\& commit b1b3dab48344cff6de4087efca3dbd63548ab5e2
+\& Author: Leon Brocard <acme@astray.com>
+\& Date:   Fri Dec 19 17:02:59 2008 +0000
+\&
+\&   Rename Leon Brocard to Orange Brocard
+\&
+\& diff \-\-git a/AUTHORS b/AUTHORS
+\& index 293dd70..722c93e 100644
+\& \-\-\- a/AUTHORS
+\& +++ b/AUTHORS
+\& @@ \-541,7 +541,7 @@ Lars Hecking                 <lhecking@nmrc.ucc.ie>
+\&  Laszlo Molnar                  <laszlo.molnar@eth.ericsson.se>
+\&  Leif Huhn                      <leif@hale.dkstat.com>
+\&  Len Johnson                    <lenjay@ibm.net>
+\& \-Leon Brocard                   <acme@astray.com>
+\& +Orange Brocard                 <acme@astray.com>
+\&  Les Peters                     <lpeters@aol.net>
+\&  Lesley Binks                   <lesley.binks@gmail.com>
+\&  Lincoln D. Stein               <lstein@cshl.org>
+.Ve
+.PP
+If you are a committer to Perl and you think the patch is good, you can
+then merge it into blead then push it out to the main repository:
+.PP
+.Vb 3
+\&  % git checkout blead
+\&  % git merge experimental
+\&  % git push origin blead
+.Ve
+.PP
+If you want to delete your temporary branch, you may do so with:
+.PP
+.Vb 7
+\& % git checkout blead
+\& % git branch \-d experimental
+\& error: The branch \*(Aqexperimental\*(Aq is not an ancestor of your current
+\& HEAD.  If you are sure you want to delete it, run \*(Aqgit branch \-D
+\& experimental\*(Aq.
+\& % git branch \-D experimental
+\& Deleted branch experimental.
+.Ve
+.SS "Committing to blead"
+.IX Subsection "Committing to blead"
+The 'blead' branch will become the next production release of Perl.
+.PP
+Before pushing \fIany\fR local change to blead, it's incredibly important
+that you do a few things, lest other committers come after you with
+pitchforks and torches:
+.IP \(bu 4
+Make sure you have a good commit message. See "Commit
+message" in perlhack for details.
+.IP \(bu 4
+Run the test suite. You might not think that one typo fix would break a
+test file. You'd be wrong. Here's an example of where not running the
+suite caused problems. A patch was submitted that added a couple of
+tests to an existing \fI.t\fR. It couldn't possibly affect anything else, so
+no need to test beyond the single affected \fI.t\fR, right?  But, the
+submitter's email address had changed since the last of their
+submissions, and this caused other tests to fail. Running the test
+target given in the next item would have caught this problem.
+.IP \(bu 4
+If you don't run the full test suite, at least \f(CW\*(C`make test_porting\*(C'\fR.
+This will run basic sanity checks. To see which sanity checks, have a
+look in \fIt/porting\fR.
+.IP \(bu 4
+If you make any changes that affect miniperl or core routines that have
+different code paths for miniperl, be sure to run \f(CW\*(C`make minitest\*(C'\fR.
+This will catch problems that even the full test suite will not catch
+because it runs a subset of tests under miniperl rather than perl.
+.SS "On merging and rebasing"
+.IX Subsection "On merging and rebasing"
+Simple, one-off commits pushed to the 'blead' branch should be simple
+commits that apply cleanly.  In other words, you should make sure your
+work is committed against the current position of blead, so that you can
+push back to the master repository without merging.
+.PP
+Sometimes, blead will move while you're building or testing your
+changes.  When this happens, your push will be rejected with a message
+like this:
+.PP
+.Vb 7
+\& To ssh://perl5.git.perl.org/perl.git
+\&  ! [rejected]        blead \-> blead (non\-fast\-forward)
+\& error: failed to push some refs to \*(Aqssh://perl5.git.perl.org/perl.git\*(Aq
+\& To prevent you from losing history, non\-fast\-forward updates were
+\& rejected Merge the remote changes (e.g. \*(Aqgit pull\*(Aq) before pushing
+\& again.  See the \*(AqNote about fast\-forwards\*(Aq section of \*(Aqgit push \-\-help\*(Aq
+\& for details.
+.Ve
+.PP
+When this happens, you can just \fIrebase\fR your work against the new
+position of blead, like this (assuming your remote for the master
+repository is "p5p"):
+.PP
+.Vb 2
+\&  % git fetch p5p
+\&  % git rebase p5p/blead
+.Ve
+.PP
+You will see your commits being re-applied, and you will then be able to
+push safely.  More information about rebasing can be found in the
+documentation for the \fBgit\-rebase\fR\|(1) command.
+.PP
+For larger sets of commits that only make sense together, or that would
+benefit from a summary of the set's purpose, you should use a merge
+commit.  You should perform your work on a topic branch, which you should regularly rebase
+against blead to ensure that your code is not broken by blead moving.
+When you have finished your work, please perform a final rebase and
+test.  Linear history is something that gets lost with every
+commit on blead, but a final rebase makes the history linear
+again, making it easier for future maintainers to see what has
+happened.  Rebase as follows (assuming your work was on the
+branch \f(CW\*(C`committer/somework\*(C'\fR):
+.PP
+.Vb 2
+\&  % git checkout committer/somework
+\&  % git rebase blead
+.Ve
+.PP
+Then you can merge it into master like this:
+.PP
+.Vb 3
+\&  % git checkout blead
+\&  % git merge \-\-no\-ff \-\-no\-commit committer/somework
+\&  % git commit \-a
+.Ve
+.PP
+The switches above deserve explanation.  \f(CW\*(C`\-\-no\-ff\*(C'\fR indicates that even
+if all your work can be applied linearly against blead, a merge commit
+should still be prepared.  This ensures that all your work will be shown
+as a side branch, with all its commits merged into the mainstream blead
+by the merge commit.
+.PP
+\&\f(CW\*(C`\-\-no\-commit\*(C'\fR means that the merge commit will be \fIprepared\fR but not
+\&\fIcommitted\fR.  The commit is then actually performed when you run the
+next command, which will bring up your editor to describe the commit.
+Without \f(CW\*(C`\-\-no\-commit\*(C'\fR, the commit would be made with nearly no useful
+message, which would greatly diminish the value of the merge commit as a
+placeholder for the work's description.
+.PP
+When describing the merge commit, explain the purpose of the branch, and
+keep in mind that this description will probably be used by the
+eventual release engineer when reviewing the next perldelta document.
+.PP
+If the subsequent \fIpush\fR fails then you must be careful on how you \fIrebase\fR.
+If you use
+.PP
+.Vb 1
+\&  % git rebase p5p/blead
+.Ve
+.PP
+or
+.PP
+.Vb 1
+\&  % git pull \-\-rebase
+.Ve
+.PP
+then your carefully created merge commit will be lost! To avoid this you
+can use:
+.PP
+.Vb 2
+\&  % git fetch p5p
+\&  % git rebase \-\-rebase\-merges p5p/blead
+.Ve
+.PP
+This will recreate your merge commit.
+.PP
+(Should you be stuck with an older version of git (prior to 2.18), then
+\&\f(CW\*(C`git rebase\*(C'\fR will not have the \f(CW\*(C`\-\-rebase\-merges\*(C'\fR switch, instead you
+have to use the \f(CW\*(C`\-\-preserve\-merges\*(C'\fR switch.)
+.SS "Committing to maintenance versions"
+.IX Subsection "Committing to maintenance versions"
+Maintenance versions should only be altered to add critical bug fixes,
+see perlpolicy.
+.PP
+To commit to a maintenance version of perl, you need to create a local
+tracking branch:
+.PP
+.Vb 1
+\&  % git checkout \-\-track \-b maint\-5.005 origin/maint\-5.005
+.Ve
+.PP
+This creates a local branch named \f(CW\*(C`maint\-5.005\*(C'\fR, which tracks the
+remote branch \f(CW\*(C`origin/maint\-5.005\*(C'\fR. Then you can pull, commit, merge
+and push as before.
+.PP
+You can also cherry-pick commits from blead and another branch, by
+using the \f(CW\*(C`git cherry\-pick\*(C'\fR command. It is recommended to use the
+\&\fB\-x\fR option to \f(CW\*(C`git cherry\-pick\*(C'\fR in order to record the SHA1 of the
+original commit in the new commit message.
+.PP
+Before pushing any change to a maint version, make sure you've
+satisfied the steps in "Committing to blead" above.
+.SS "Using a smoke-me branch to test changes"
+.IX Subsection "Using a smoke-me branch to test changes"
+Sometimes a change affects code paths which you cannot test on the OSes
+which are directly available to you and it would be wise to have users
+on other OSes test the change before you commit it to blead.
+.PP
+Fortunately, there is a way to get your change smoke-tested on various
+OSes: push it to a "smoke-me" branch and wait for certain automated
+smoke-testers to report the results from their OSes.
+A "smoke-me" branch is identified by the branch name: specifically, as
+seen on github.com it must be a local branch whose first name
+component is precisely \f(CW\*(C`smoke\-me\*(C'\fR.
+.PP
+The procedure for doing this is roughly as follows (using the example of
+tonyc's smoke-me branch called win32stat):
+.PP
+First, make a local branch and switch to it:
+.PP
+.Vb 1
+\&  % git checkout \-b win32stat
+.Ve
+.PP
+Make some changes, build perl and test your changes, then commit them to
+your local branch. Then push your local branch to a remote smoke-me
+branch:
+.PP
+.Vb 1
+\&  % git push origin win32stat:smoke\-me/tonyc/win32stat
+.Ve
+.PP
+Now you can switch back to blead locally:
+.PP
+.Vb 1
+\&  % git checkout blead
+.Ve
+.PP
+and continue working on other things while you wait a day or two,
+keeping an eye on the results reported for your smoke-me branch at
+<http://perl.develop\-help.com/?b=smoke\-me/tonyc/win32state>.
+.PP
+If all is well then update your blead branch:
+.PP
+.Vb 1
+\&  % git pull
+.Ve
+.PP
+then checkout your smoke-me branch once more and rebase it on blead:
+.PP
+.Vb 1
+\&  % git rebase blead win32stat
+.Ve
+.PP
+Now switch back to blead and merge your smoke-me branch into it:
+.PP
+.Vb 2
+\&  % git checkout blead
+\&  % git merge win32stat
+.Ve
+.PP
+As described earlier, if there are many changes on your smoke-me branch
+then you should prepare a merge commit in which to give an overview of
+those changes by using the following command instead of the last
+command above:
+.PP
+.Vb 1
+\&  % git merge win32stat \-\-no\-ff \-\-no\-commit
+.Ve
+.PP
+You should now build perl and test your (merged) changes one last time
+(ideally run the whole test suite, but failing that at least run the
+\&\fIt/porting/*.t\fR tests) before pushing your changes as usual:
+.PP
+.Vb 1
+\&  % git push origin blead
+.Ve
+.PP
+Finally, you should then delete the remote smoke-me branch:
+.PP
+.Vb 1
+\&  % git push origin :smoke\-me/tonyc/win32stat
+.Ve
+.PP
+(which is likely to produce a warning like this, which can be ignored:
+.PP
+.Vb 4
+\& remote: fatal: ambiguous argument
+\&                                  \*(Aqrefs/heads/smoke\-me/tonyc/win32stat\*(Aq:
+\& unknown revision or path not in the working tree.
+\& remote: Use \*(Aq\-\-\*(Aq to separate paths from revisions
+.Ve
+.PP
+) and then delete your local branch:
+.PP
+.Vb 1
+\&  % git branch \-d win32stat
+.Ve