chiark / gitweb /
changelog: Document some recent changes
[dgit.git] / dgit-sponsorship.7.pod
1 =head1 NAME
2
3 dgit-sponsorship - tutorial for Debian upload sponsorship, using git
4
5 =head1 INTRODUCTION AND SCOPE
6
7 This tutorial describes how a Debian sponsored contributor
8 and
9 a sponsoring DD (or DM)
10 can collaborate and publish using git.
11
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.)
16
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.
21
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.
25
26 =head1 SPONSEE WORKFLOW
27
28 This section is addressed to the sponsee:
29
30 =head2 General
31
32 You should prepare the package as if you were going
33 to upload it with C<dgit push> yourself.
34
35 For a straightforward NMU, consult L<dgit-nmu-simple(7)>.
36
37 If you are the (prospective) maintainer,
38 you can adopt any suitable (dgit-compatible)
39 git workflow.
40 The L<dgit-maint-*(7)> tutorials describe some of the possibilities.
41
42 =head2 Upload preparation
43
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).
49
50 At the point where you would,
51 if you were a DD, 
52 do the actual upload
53 by running dgit push,
54 you hand off to your sponsor.
55
56 If you were going to use one of the
57 C<--quilt=>
58 options to dgit, or
59 C<dgit --gbp> or C<dgit --dpm>,
60 you must specify that in your handoff email - see below.
61
62 =head2 git+origs based handoff
63
64 The elements of the handoff consists of:
65
66 =over
67
68 =item *
69
70 The git branch.
71
72 =item *
73
74 Any .orig tarballs which will be needed,
75 or sample git-archive(1)
76 or gbp-buildpackage(1)
77 command(s) to generate them.
78
79 =item *
80
81 A sample dgit push command, containing
82 any dgit --quilt=, --gbp or --dpm option needed
83
84 =item *
85
86 Plus of course all the usual information about the state
87 of the package,
88 any caveats or areas you would like the sponsor to focus their review,
89 constraints about upload timing, etc.
90
91 =back
92
93 If the handoff is done by email,
94 the elements above should be a in a single, signed, message.
95 This could be an RFS submission
96 against the sponsorship-requests pseudo-package.
97
98 =head3 git branch
99
100 =over 4
101
102 The sponsee should push their HEAD as a git branch
103 to any suitable git server.
104 They can use their own git server;
105 alioth is another possibility.
106
107 The branch names used by the sponsee on their local machine,
108 and on the server, do not matter.
109
110 Instead, the sponsee should include the
111 git commit id of their HEAD
112 in their handover email.
113
114 =back
115
116 =head3 orig tarballs
117
118 =over 4
119
120 If there are any .origs that are not in the archive already,
121 the sponsor will need them as part of the upload.
122
123 If the sponsee generated these tarballs with git-archive(1)
124 or gbp-buildpackage(1),
125 they can simply include a sample invocation of git-archive(1)
126 or ensure that a suitable gbp.conf is present
127 in the source package
128 to generate the tarball.
129
130 Otherwise, the simplest approach is to
131 commit the orig tarballs
132 with pristine-tar(1), e.g.
133
134 =over 4
135
136     % pristine-tar commit ../foo_1.2.3.orig.tar.xz upstream/1.2.3
137
138 =back
139
140 and be sure to push the pristine-tar branch.
141 If you are using git-buildpackage(1), just pass
142 I<--git-pristine-tar> and I<--git-pristine-tar-commit>.
143
144 Alternatively,
145 the sponsee can put them on a suitable webserver,
146 or attach to the e-mail,
147 if they are small.
148
149 The sponsee should quote sha256sums of the .origs in their
150 handoff email,
151 unless they supplied commands to generate them.
152
153 =back
154
155 =head3 quilt options
156
157 =over 4
158
159 Some workflows involve git branches which are not natively
160 dgit-compatible.
161 Normally dgit will convert them as needed, during push.
162
163 Supply a sample "dgit push" command
164 including any
165 C<--gbp> (aka C<--quilt=gbp>),
166 C<--dpm> (aka C<--quilt=dpm>),
167 or other C<--quilt=> option
168 they need to use.
169 e.g.
170
171 =over 4
172
173     % dgit --gbp push
174
175 =back
176
177 =back
178
179 =head1 SPONSOR WORKFLOW
180
181 This part is addressed to the sponsor:
182
183 =head2 Receiving and validating the sponsorship request
184
185 You should check the signature on the email.
186
187 Use C<git fetch> or C<git clone> to obtain the git branch
188 prepared by your sponsee,
189 and obtain any .origs mentioned by the sponsee
190 (to extract .origs committed with pristine-tar,
191 you can use origtargz(1),
192 or use "gbp clone --pristine-tar".)
193
194 Check the git commit ID of the sponsee's branch tip,
195 and the sha256sums of the .origs,
196 against the handoff email.
197
198 Now you can check out the branch tip,
199 and do your substantive review.
200
201 =head2 Dealing with branches that want --quilt=
202
203 If your sponsee mentioned a C<--quilt>
204 option, and you don't want to grapple with their preferred tree format,
205 you can convert their tree into the standard dgit view:
206
207 =over 4
208
209     % dgit -wgf --quilt=foo --dgit-view-save=unquilted quilt-fixup
210     % git checkout unquilted
211
212 =back
213
214 You should check that what you're looking at is a descendant of
215 the sponsee's branch.
216
217 =head2 Some hints which may help the review
218
219 C<dgit fetch sid> will get you an up-to-date
220 C<refs/remotes/dgit/dgit/sid>
221 showing what's in the archive already.
222
223 C<dgit -wgf --damp-run push>
224 will check that dgit can build an appropriate source package.
225
226 There is no need to run debdiff.
227 dgit will not upload anything that doesn't unpack
228 to exactly the git commit you are pushing,
229 so you can rely on what you see in C<git diff>.
230
231 =head2 Doing the upload
232
233 When you have completed your source review,
234 and use
235 C<dgit -wgf [--quilt=...] sbuild -A -C>
236 or similar, to to the build, and then
237 C<dgit -wgf [--quilt=...] push>
238 to do the upload.
239
240 Check whether the sponsee made a debian/I<version> tag.
241 If they did,
242 ensure you have their tag in the repository you are pushing from,
243 or pass C<--no-dep14tag>.
244 This avoids identically named, non-identical tags,
245 which can be confusing.
246
247 (It is possible to upload from
248 the quilt-cache dgit view.
249 If you want to do this,
250 B<do not> pass the C<--quilt> or C<--gbp> or C<--dpm> options again,
251 and B<do> pass C<--no-dep14tag>,
252 since the debian/I<version> tag
253 should go on the sponsee's branch.)
254
255 If this was the first upload done with dgit,
256 you may need to pass
257 C<--overwrite>
258 to dgit.
259
260 Alternatively,
261 if this was the first ever dgit push of the package,
262 you can pass C<--deliberately-not-fast-forward>
263 instead of C<--overwrite>.
264 This avoids introducing a new origin commit
265 into the dgit view of
266 the sponsee's git history
267 which is unnecessary and could be confusing.
268
269 =head1 SPONSORING A NON-GIT-USING SPONSEE
270
271 This part is addressed to the sponsor:
272
273 If your sponsee does not use git,
274 you can still do your review with git,
275 and use dgit for the upload.
276
277 Your sponsee will provide you with a source package:
278 that is, a .dsc and the files it refers to.
279 Obtain these files, and check signatures as appropriate.
280 Then:
281
282 =over 4
283
284     % dgit clone PACKAGE
285     % cd PACKAGE
286     % dgit import-dsc /path/to/sponsee's.dsc +sponsee
287     % git checkout sponsee
288
289 =back
290
291 Or for an entirely new package:
292
293 =over 4
294
295     % mkdir PACKAGE
296     % cd PACKAGE
297     % git init
298     % dgit -pPACKAGE import-dsc /path/to/sponsee's.dsc +sponsee
299
300 =back
301
302 This will leave you looking at the sponsee's package,
303 formatted as a dgit branch.
304
305 When you have finished your review and your tests,
306 you can do the
307 dgit sbuild and
308 dgit push directly from the "sponsee" branch.
309
310 You will need to pass
311 C<--overwrite>
312 to dgit push for every successive upload.
313 This disables a safety catch which would normally spot
314 situations where changes are accidentally lost.
315 When your sponsee is sending you source packages -
316 perhaps multiple source pacakges with the same version number -
317 these safety catches are inevitably ineffective.
318
319 =head1 SEE ALSO
320
321 dgit(1), dgit(7), dgit-nmu-simple(7), dgit-maint-*(7)