.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "dgit-sponsorship 7"
.TH dgit-sponsorship 7 "Debian Project" "perl v5.28.1" "dgit"
.\" 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"
dgit\-sponsorship \- tutorial for Debian upload sponsorship, using git
.SH "INTRODUCTION AND SCOPE"
.IX Header "INTRODUCTION AND SCOPE"
This tutorial describes how a Debian sponsored contributor
and
a sponsoring \s-1DD\s0 (or \s-1DM\s0)
can collaborate and publish using git.
.PP
The sponsor must be intending to use dgit for the upload.
(If the sponsor does not use dgit,
it is not possible to properly publish
a sponsee's git branch.)
.PP
It is best if the sponsee also uses dgit;
but also covered (later on) is the case where
the sponsee provides a proposed upload in source package form,
but the sponsor would like to work in git.
.PP
This tutorial does not provide a checklist for the sponsor's review.
Both contributors are expected to be familiar with Debian
packaging and Debian's processes, and with git.
.SH "SPONSEE WORKFLOW"
.IX Header "SPONSEE WORKFLOW"
This section is addressed to the sponsee:
.SS "General"
.IX Subsection "General"
You should prepare the package as if you were going
to upload it with \f(CW\*(C`dgit push\-source\*(C'\fR or \f(CW\*(C`dgit push\*(C'\fR yourself.
.PP
For a straightforward \s-1NMU,\s0 consult \fBdgit\-nmu\-simple\fR\|(7).
.PP
If you are the (prospective) maintainer,
you can adopt any suitable (dgit-compatible)
git workflow.
The dgit\-maint\-*(7) tutorials describe some of the possibilities.
.SS "Upload preparation"
.IX Subsection "Upload preparation"
You should go through all of the steps 
a self-uploading maintainer would do,
including building for ad hoc tests,
and checking via a formal build (eg using \f(CW\*(C`dgit sbuild\*(C'\fR)
that the package builds on sid (or the target release).
.PP
At the point where you would,
if you were a \s-1DD,\s0 
do the actual upload
by running dgit push,
you hand off to your sponsor.
.PP
If you were going to use one of the
\&\f(CW\*(C`\-\-quilt=\*(C'\fR
options to dgit, or
\&\f(CW\*(C`dgit \-\-gbp\*(C'\fR or \f(CW\*(C`dgit \-\-dpm\*(C'\fR,
you must specify that in your handoff email \- see below.
.SS "git+origs based handoff"
.IX Subsection "git+origs based handoff"
The elements of the handoff consists of:
.IP "\(bu" 4
The git branch.
.IP "\(bu" 4
Any .orig tarballs which will be needed,
or sample \fBgit\-archive\fR\|(1)
or \fBgbp\-buildpackage\fR\|(1)
command(s) to generate them.
.IP "\(bu" 4
A sample dgit push command, containing
any dgit \-\-quilt=, \-\-gbp or \-\-dpm option needed
.IP "\(bu" 4
Plus of course all the usual information about the state
of the package,
any caveats or areas you would like the sponsor to focus their review,
constraints about upload timing, etc.
.PP
If the handoff is done by email,
the elements above should be a in a single, signed, message.
This could be an \s-1RFS\s0 submission
against the sponsorship-requests pseudo-package.
.PP
\fIgit branch\fR
.IX Subsection "git branch"
.Sp
.RS 4
The sponsee should push their \s-1HEAD\s0 as a git branch
to any suitable git server.
They can use their own git server;
salsa is another possibility.
.Sp
The branch names used by the sponsee on their local machine,
and on the server, do not matter.
.Sp
Instead, the sponsee should include the
git commit id of their \s-1HEAD\s0
in their handover email.
.RE
.PP
\fIorig tarballs\fR
.IX Subsection "orig tarballs"
.Sp
.RS 4
If there are any .origs that are not in the archive already,
the sponsor will need them as part of the upload.
.Sp
If the sponsee generated these tarballs with \fBgit\-archive\fR\|(1)
or \fBgbp\-buildpackage\fR\|(1),
they can simply include a sample invocation of \fBgit\-archive\fR\|(1)
or ensure that a suitable gbp.conf is present
in the source package
to generate the tarball.
.Sp
Otherwise, the simplest approach is to
commit the orig tarballs
with \fBpristine\-tar\fR\|(1), e.g.
.Sp
.Vb 1
\&    % pristine\-tar commit ../foo_1.2.3.orig.tar.xz upstream/1.2.3
.Ve
.RE
.RS 4
.Sp
and be sure to push the pristine-tar branch.
If you are using \fBgit\-buildpackage\fR\|(1), just pass
\&\fI\-\-git\-pristine\-tar\fR and \fI\-\-git\-pristine\-tar\-commit\fR.
.Sp
Alternatively,
the sponsee can put them on a suitable webserver,
or attach to the e\-mail,
if they are small.
.Sp
The sponsee should quote sha256sums of the .origs in their
handoff email,
unless they supplied commands to generate them.
.RE
.PP
\fIquilt options\fR
.IX Subsection "quilt options"
.Sp
.RS 4
Some workflows involve git branches which are not natively
dgit-compatible.
Normally dgit will convert them as needed, during push.
.Sp
Supply a sample \*(L"dgit push\*(R" command
including any
\&\f(CW\*(C`\-\-gbp\*(C'\fR (aka \f(CW\*(C`\-\-quilt=gbp\*(C'\fR),
\&\f(CW\*(C`\-\-dpm\*(C'\fR (aka \f(CW\*(C`\-\-quilt=dpm\*(C'\fR),
or other \f(CW\*(C`\-\-quilt=\*(C'\fR option
they need to use.
e.g.
.Sp
.Vb 1
\&    % dgit \-\-gbp push
.Ve
.RE
.RS 4
.RE
.SH "SPONSOR WORKFLOW"
.IX Header "SPONSOR WORKFLOW"
This part is addressed to the sponsor:
.SS "Receiving and validating the sponsorship request"
.IX Subsection "Receiving and validating the sponsorship request"
You should check the signature on the email.
.PP
Use \f(CW\*(C`git fetch\*(C'\fR or \f(CW\*(C`git clone\*(C'\fR to obtain the git branch
prepared by your sponsee,
and obtain any .origs mentioned by the sponsee
(to extract .origs committed with pristine-tar,
you can use \fBorigtargz\fR\|(1),
or use \*(L"gbp clone \-\-pristine\-tar\*(R".)
.PP
Check the git commit \s-1ID\s0 of the sponsee's branch tip,
and the sha256sums of the .origs,
against the handoff email.
.PP
Now you can check out the branch tip,
and do your substantive review.
.SS "Dealing with branches that want \-\-quilt="
.IX Subsection "Dealing with branches that want --quilt="
If your sponsee mentioned a \f(CW\*(C`\-\-quilt\*(C'\fR
option, and you don't want to grapple with their preferred tree format,
you can convert their tree into the standard dgit view:
.Sp
.Vb 2
\&    % dgit \-wgf \-\-quilt=foo \-\-dgit\-view\-save=unquilted quilt\-fixup
\&    % git checkout unquilted
.Ve
.PP
You should check that what you're looking at is a descendant of
the sponsee's branch.
.SS "Some hints which may help the review"
.IX Subsection "Some hints which may help the review"
\&\f(CW\*(C`dgit fetch sid\*(C'\fR will get you an up-to-date
\&\f(CW\*(C`refs/remotes/dgit/dgit/sid\*(C'\fR
showing what's in the archive already.
.PP
\&\f(CW\*(C`dgit \-wgf \-\-damp\-run push\-source\*(C'\fR
will check that dgit can build an appropriate source package.
.PP
There is no need to run debdiff.
dgit will not upload anything that doesn't unpack
to exactly the git commit you are pushing,
so you can rely on what you see in \f(CW\*(C`git diff\*(C'\fR.
.SS "Doing the upload"
.IX Subsection "Doing the upload"
When you have completed your source review,
and use
\&\f(CW\*(C`dgit \-wgf [\-\-quilt=...] sbuild \-A \-C\*(C'\fR
or similar, to to the build, and then
\&\f(CW\*(C`dgit \-wgf [\-\-quilt=...] push\-source\*(C'\fR
or
\&\f(CW\*(C`dgit \-wgf [\-\-quilt=...] push\*(C'\fR
to do the upload.
.PP
Check whether the sponsee made a debian/\fIversion\fR tag.
If they did,
ensure you have their tag in the repository you are pushing from,
or pass \f(CW\*(C`\-\-no\-dep14tag\*(C'\fR.
This avoids identically named, non-identical tags,
which can be confusing.
.PP
(It is possible to upload from
the quilt-cache dgit view.
If you want to do this,
\&\fBdo not\fR pass the \f(CW\*(C`\-\-quilt\*(C'\fR or \f(CW\*(C`\-\-gbp\*(C'\fR or \f(CW\*(C`\-\-dpm\*(C'\fR options again,
and \fBdo\fR pass \f(CW\*(C`\-\-no\-dep14tag\*(C'\fR,
since the debian/\fIversion\fR tag
should go on the sponsee's branch.)
.PP
If this was the first upload done with dgit,
you may need to pass
\&\f(CW\*(C`\-\-overwrite\*(C'\fR
to dgit.
.PP
Alternatively,
if this was the first ever dgit push of the package,
you can pass \f(CW\*(C`\-\-deliberately\-not\-fast\-forward\*(C'\fR
instead of \f(CW\*(C`\-\-overwrite\*(C'\fR.
This avoids introducing a new origin commit
into the dgit view of
the sponsee's git history
which is unnecessary and could be confusing.
.SH "SPONSORING A NON-GIT-USING SPONSEE"
.IX Header "SPONSORING A NON-GIT-USING SPONSEE"
This part is addressed to the sponsor:
.PP
If your sponsee does not use git,
you can still do your review with git,
and use dgit for the upload.
.PP
Your sponsee will provide you with a source package:
that is, a .dsc and the files it refers to.
Obtain these files, and check signatures as appropriate.
Then:
.Sp
.Vb 4
\&    % dgit clone PACKAGE
\&    % cd PACKAGE
\&    % dgit import\-dsc /path/to/sponsee\*(Aqs.dsc +sponsee
\&    % git checkout sponsee
.Ve
.PP
Or for an entirely new package:
.Sp
.Vb 4
\&    % mkdir PACKAGE
\&    % cd PACKAGE
\&    % git init
\&    % dgit \-pPACKAGE import\-dsc /path/to/sponsee\*(Aqs.dsc +sponsee
.Ve
.PP
This will leave you looking at the sponsee's package,
formatted as a dgit branch.
.PP
When you have finished your review and your tests,
you can do the
dgit sbuild and
dgit push directly from the \*(L"sponsee\*(R" branch.
.PP
You will need to pass
\&\f(CW\*(C`\-\-overwrite\*(C'\fR
to dgit push for every successive upload.
This disables a safety catch which would normally spot
situations where changes are accidentally lost.
When your sponsee is sending you source packages \-
perhaps multiple source packages with the same version number \-
these safety catches are inevitably ineffective.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBdgit\fR\|(1), \fBdgit\fR\|(7), \fBdgit\-nmu\-simple\fR\|(7), dgit\-maint\-*(7)