3 dgit-sponsorship - tutorial for Debian upload sponsorship, using git
5 =head1 INTRODUCTION AND SCOPE
7 This tutorial describes how a Debian sponsored contributor
9 their sponsoring DD (or DM)
10 can collaborate and publish using git.
12 The sponsor must to be intending to use dgit for the upload.
13 (If the sponsor does not use dgit,
14 it is not possible to properly publish
15 a sponsee's git branch.)
17 It is best if the sponsee also uses dgit;
18 but also covered (later on) is the case where
19 the sponsee provides a proposed upload in source package form,
20 but the sponsor would like to work in git.
22 This tutorial does not provide a checklist for the sponsor's review.
23 Both contributors are expected to be familiar with Debian
24 packaging and Debian's processes, and with git.
26 =head1 SPONSEE WORKFLOW
28 This section is addressed to the sponsee:
32 You should prepare the package as if you were going
33 to upload it with C<dgit push> yourself.
35 For a straightforward NMU, consult L<dgit-nmu-simple(7)>.
37 If you are the (prospective) maintainer,
38 you can adopt any suitable (dgit-compatible)
40 The L<dgit-maint-*(7)> tutorials describe some of the possibilities.
42 =head2 Upload preparation
44 You should go through all of the steps
45 a self-uploading maintainer would do,
46 including building for ad hoc tests,
47 and checking via a formal build (eg using C<dgit sbuild>)
48 that the package builds on sid (or the target release).
50 At the point where you would,
54 you hand off to your sponsor.
56 If you were going to use one of the
59 C<dgit --gbp> or C<dgit --dpm>,
60 you must specify that in your handoff email - see below.
62 =head1 GIT+ORIGS BASED HANDOFF
64 The elements of the handoff consists of:
74 Any .orig tarballs which will be needed.
78 Any dgit --quilt= (or --gbp or --dpm) option needed
82 Plus of course all the usual information about the state
84 any caveats or areas you would like the sponsor to focus their review,
85 constraints about upload timing, etc.
89 If the handoff is done by email,
90 the elements above should be a in a single, signed, message.
94 The sponsee should push their HEAD as a git branch
95 to any suitable git server.
96 They can use their own git server;
97 alioth is another possibility.
99 The branch names used by the sponsee on their local machine,
100 and on the server, do not matter.
102 The sponsee should not make a C<debian/>I<version> tag.
104 Instead, the sponsor should include the
105 git commit id of their HEAD
106 in their handover email.
110 If there are any .origs that are not in the archive already,
111 the sponsor will need them as part of the upload.
113 The sponsee can put them on a suitable webserver,
114 or attach to an email.
116 The sponsee should quote sha256sums of the .origs in their
121 Some workflows involve git branches which are not natively
123 Normally dgit will convert them as needed, during push.
124 You need to tell your sponsor if they need to use
125 C<--gbp> (aka C<--quilt=gbp>),
126 C<--dpm> (aka C<--quilt=dpm>),
127 or one of the other C<--quilt=> options.
130 =head1 SPONSOR WORKFLOW
132 This part is addressed to the sponsor:
134 =head2 Receiving and validating the sponsorship request
136 You should check the signature on the email.
138 Use C<git fetch> to fetch the git branch
139 prepared by your sponsee,
140 and obtain any .origs mentioned by the sponsee.
142 Check the git commit ID of the sponsee's branch tip,
143 and the sha256sums of the .origs,
144 against the handoff email.
146 Now you can check out the branch tip,
147 and do your substantive review.
149 =head2 Dealing with branches that want --quilt=
151 If your sponsee mentioned a C<--quilt>
152 option, and you don't want to grapple with their preferred tree format,
153 you can convert their tree into the standard dgit view:
157 % dgit -wgf quilt-fixup
158 [ Watch for a message about split brain, and if so: ]
159 % git checkout -b dgit-view-for-review refs/dgit-intern/quilt-cache
163 You should check that what you're looking at is a descendant of
164 the sponsee's branch.
166 =head2 Some hints which may help the review
168 C<dgit fetch sid> will get you an up-to-date
169 C<refs/remotes/dgit/dgit/sid>
170 showing what's in the archive already.
172 C<dgit -wgf --damp-run push>
173 will check that dgit can build an appropriate source package.
175 There is no need to run debdiff.
176 dgit will not upload anything that doesn't unpack
177 to exactly the git commit you are pushing,
178 so you can rely on what you see in C<git diff>.
180 =head2 Doing the upload
182 When you have completed your source review,
184 C<dgit -wgf [--quilt=...] sbuild -A -C>
185 or similar, to to the build, and then
186 C<dgit -wgf [--quilt=...] push>
189 (If you switched to the quilt-cache dgit view,
190 B<do not> pass the --quilt or --gbp or --dpm option again.)
192 If this was the first upload done with dgit,
198 =head1 SPONSORING A NON-GIT-USING SPONSEE
200 This part is addressed to the sponsor:
202 If your sponsee does not use git,
203 you can still do your review with git,
204 and use dgit for the upload.
206 Your sponsee will provide you with a source package:
207 that is, a .dsc and the files it refers to.
208 Obtain these files, and check signatures as appropriate.
215 % dgit import-dsc /path/to/sponsee's.dsc +sponsee
216 % git checkout sponsee
220 This will leave you looking at the sponsee's package,
221 formatted as a dgit branch.
223 When you have finished your review and your tests,
226 dgit push directly from the "sponsee" branch.
228 You will need to pass
230 to dgit push for every successive upload.
231 This disables a safety catch which would normally spot
232 situations where changes are accidentally lost.
233 When your sponsee is sending you source packages -
234 perhaps multiple source pacakges with the same version number -
235 these safety catches are inevitably ineffective.
239 dgit(1), dgit(7), dgit-nmu-simple(7), dgit-maint-*(7)