1dgit-sponsorship(7)                  dgit                  dgit-sponsorship(7)
2
3
4

NAME

6       dgit-sponsorship - tutorial for Debian upload sponsorship, using git
7

INTRODUCTION AND SCOPE

9       This tutorial describes how a Debian sponsored contributor and a
10       sponsoring DD (or DM) can collaborate and publish using git.
11
12       The sponsor must be intending to use dgit for the upload.  (If the
13       sponsor does not use dgit, it is not possible to properly publish a
14       sponsee's git branch.)
15
16       It is best if the sponsee also uses dgit; but also covered (later on)
17       is the case where the sponsee provides a proposed upload in source
18       package form, but the sponsor would like to work in git.
19
20       This tutorial does not provide a checklist for the sponsor's review.
21       Both contributors are expected to be familiar with Debian packaging and
22       Debian's processes, and with git.
23

SPONSEE WORKFLOW

25       This section is addressed to the sponsee:
26
27   General
28       You should prepare the package as if you were going to upload it with
29       "dgit push-source" or "dgit push" yourself.
30
31       For a straightforward NMU, consult dgit-nmu-simple(7).
32
33       If you are the (prospective) maintainer, you can adopt any suitable
34       (dgit-compatible) git workflow.  The dgit-maint-*(7) tutorials describe
35       some of the possibilities.
36
37   Upload preparation
38       You should go through all of the steps a self-uploading maintainer
39       would do, including building for ad hoc tests, and checking via a
40       formal build (eg using "dgit sbuild") that the package builds on sid
41       (or the target release).
42
43       At the point where you would, if you were a DD, do the actual upload by
44       running dgit push, you hand off to your sponsor.
45
46       If you were going to use one of the "--quilt=" options to dgit, or
47       "dgit --gbp" or "dgit --dpm", you must specify that in your handoff
48       email - see below.
49
50   git+origs based handoff
51       The elements of the handoff consists of:
52
53       •   The git branch.
54
55       •   Any .orig tarballs which will be needed, or sample git-archive(1)
56           or gbp-buildpackage(1) command(s) to generate them.
57
58       •   A sample dgit push command, containing any dgit --quilt=, --gbp or
59           --dpm option needed
60
61       •   Plus of course all the usual information about the state of the
62           package, any caveats or areas you would like the sponsor to focus
63           their review, constraints about upload timing, etc.
64
65       If the handoff is done by email, the elements above should be a in a
66       single, signed, message.  This could be an RFS submission against the
67       sponsorship-requests pseudo-package.
68
69       git branch
70
71           The sponsee should push their HEAD as a git branch to any suitable
72           git server.  They can use their own git server; salsa is another
73           possibility.
74
75           The branch names used by the sponsee on their local machine, and on
76           the server, do not matter.
77
78           Instead, the sponsee should include the git commit id of their HEAD
79           in their handover email.
80
81       orig tarballs
82
83           If there are any .origs that are not in the archive already, the
84           sponsor will need them as part of the upload.
85
86           If the sponsee generated these tarballs with git-archive(1) or
87           gbp-buildpackage(1), they can simply include a sample invocation of
88           git-archive(1) or ensure that a suitable gbp.conf is present in the
89           source package to generate the tarball.
90
91           Otherwise, the simplest approach is to commit the orig tarballs
92           with pristine-tar(1), e.g.
93
94               % pristine-tar commit ../foo_1.2.3.orig.tar.xz upstream/1.2.3
95
96           and be sure to push the pristine-tar branch.  If you are using
97           git-buildpackage(1), just pass --git-pristine-tar and
98           --git-pristine-tar-commit.
99
100           Alternatively, the sponsee can put them on a suitable webserver, or
101           attach to the e-mail, if they are small.
102
103           The sponsee should quote sha256sums of the .origs in their handoff
104           email, unless they supplied commands to generate them.
105
106       quilt options
107
108           Some workflows involve git branches which are not natively dgit-
109           compatible.  Normally dgit will convert them as needed, during
110           push.
111
112           Supply a sample "dgit push" command including any "--gbp" (aka
113           "--quilt=gbp"), "--dpm" (aka "--quilt=dpm"), or other "--quilt="
114           option they need to use.  e.g.
115
116               % dgit --gbp push
117
119       This part is addressed to the sponsor:
120
121   Receiving and validating the sponsorship request
122       You should check the signature on the email.
123
124       Use "git fetch" or "git clone" to obtain the git branch prepared by
125       your sponsee, and obtain any .origs mentioned by the sponsee (to
126       extract .origs committed with pristine-tar, you can use origtargz(1),
127       or use "gbp clone --pristine-tar".)
128
129       Check the git commit ID of the sponsee's branch tip, and the sha256sums
130       of the .origs, against the handoff email.
131
132       Now you can check out the branch tip, and do your substantive review.
133
134   Dealing with branches that want --quilt=
135       If your sponsee mentioned a "--quilt" option, and you don't want to
136       grapple with their preferred tree format, you can convert their tree
137       into the standard dgit view:
138
139           % dgit -wgf --quilt=foo --dgit-view-save=unquilted quilt-fixup
140           % git checkout unquilted
141
142       You should check that what you're looking at is a descendant of the
143       sponsee's branch.
144
145   Some hints which may help the review
146       "dgit fetch sid" will get you an up-to-date
147       "refs/remotes/dgit/dgit/sid" showing what's in the archive already.
148
149       "dgit -wgf --damp-run push-source" will check that dgit can build an
150       appropriate source package.
151
152       There is no need to run debdiff.  dgit will not upload anything that
153       doesn't unpack to exactly the git commit you are pushing, so you can
154       rely on what you see in "git diff".
155
156   Doing the upload
157       When you have completed your source review, and use "dgit -wgf
158       [--quilt=...] sbuild -A -C" or similar, to to the build, and then "dgit
159       -wgf [--quilt=...] push-source" or "dgit -wgf [--quilt=...] push" to do
160       the upload.
161
162       Check whether the sponsee made a debian/version tag.  If they did,
163       ensure you have their tag in the repository you are pushing from, or
164       pass "--no-dep14tag".  This avoids identically named, non-identical
165       tags, which can be confusing.
166
167       (It is possible to upload from the quilt-cache dgit view.  If you want
168       to do this, do not pass the "--quilt" or "--gbp" or "--dpm" options
169       again, and do pass "--no-dep14tag", since the debian/version tag should
170       go on the sponsee's branch.)
171
172       If this was the first upload done with dgit, you may need to pass
173       "--overwrite" to dgit.
174
175       Alternatively, if this was the first ever dgit push of the package, you
176       can pass "--deliberately-not-fast-forward" instead of "--overwrite".
177       This avoids introducing a new origin commit into the dgit view of the
178       sponsee's git history which is unnecessary and could be confusing.
179

SPONSORING A NON-GIT-USING SPONSEE

181       This part is addressed to the sponsor:
182
183       If your sponsee does not use git, you can still do your review with
184       git, and use dgit for the upload.
185
186       Your sponsee will provide you with a source package: that is, a .dsc
187       and the files it refers to.  Obtain these files, and check signatures
188       as appropriate.  Then:
189
190           % dgit clone PACKAGE
191           % cd PACKAGE
192           % dgit import-dsc /path/to/sponsee's.dsc +sponsee
193           % git checkout sponsee
194
195       Or for an entirely new package:
196
197           % mkdir PACKAGE
198           % cd PACKAGE
199           % git init
200           % dgit -pPACKAGE import-dsc /path/to/sponsee's.dsc +sponsee
201
202       This will leave you looking at the sponsee's package, formatted as a
203       dgit branch.
204
205       When you have finished your review and your tests, you can do the dgit
206       sbuild and dgit push directly from the "sponsee" branch.
207
208       You will need to pass "--overwrite" to dgit push for every successive
209       upload.  This disables a safety catch which would normally spot
210       situations where changes are accidentally lost.  When your sponsee is
211       sending you source packages - perhaps multiple source packages with the
212       same version number - these safety catches are inevitably ineffective.
213

SEE ALSO

215       dgit(1), dgit(7), dgit-nmu-simple(7), dgit-maint-*(7)
216
217
218
219perl v5.34.1                    Debian Project             dgit-sponsorship(7)
Impressum