chiark / gitweb /
changelog: Fix ref to #842577
[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
76 =item *
77
78 A sample dgit push command, containing
79 any dgit --quilt=, --gbp or --dpm option needed
80
81 =item *
82
83 Plus of course all the usual information about the state
84 of the package,
85 any caveats or areas you would like the sponsor to focus their review,
86 constraints about upload timing, etc.
87
88 =back
89
90 If the handoff is done by email,
91 the elements above should be a in a single, signed, message.
92 This could be an RFS submission
93 against the sponsorship-requests pseudo-package.
94
95 =head3 git branch
96
97 =over 4
98
99 The sponsee should push their HEAD as a git branch
100 to any suitable git server.
101 They can use their own git server;
102 alioth is another possibility.
103
104 The branch names used by the sponsee on their local machine,
105 and on the server, do not matter.
106
107 The sponsee should not make a C<debian/>I<version> tag.
108
109 Instead, the sponsee should include the
110 git commit id of their HEAD
111 in their handover email.
112
113 =back
114
115 =head3 orig tarballs
116
117 =over 4
118
119 If there are any .origs that are not in the archive already,
120 the sponsor will need them as part of the upload.
121
122 The simplest approach is to
123 commit them with pristine-tar(1), e.g.
124
125 =over 4
126
127     % pristine-tar commit ../foo_1.2.3.orig.tar.xz upstream/1.2.3
128
129 =back
130
131 and be sure to push the pristine-tar branch.
132 If you are using git-buildpackage(1), just pass
133 I<--git-pristine-tar> and I<--git-pristine-tar-commit>.
134
135 Alternatively,
136 the sponsee can put them on a suitable webserver,
137 or attach to the e-mail,
138 if they are small.
139
140 The sponsee should quote sha256sums of the .origs in their
141 handoff email.
142
143 =back
144
145 =head3 quilt options
146
147 =over 4
148
149 Some workflows involve git branches which are not natively
150 dgit-compatible.
151 Normally dgit will convert them as needed, during push.
152
153 Supply a sample "dgit push" command
154 including any
155 C<--gbp> (aka C<--quilt=gbp>),
156 C<--dpm> (aka C<--quilt=dpm>),
157 or other C<--quilt=> option
158 they need to use.
159 e.g.
160
161 =over 4
162
163     % dgit --gbp push
164
165 =back
166
167 =back
168
169 =head1 SPONSOR WORKFLOW
170
171 This part is addressed to the sponsor:
172
173 =head2 Receiving and validating the sponsorship request
174
175 You should check the signature on the email.
176
177 Use C<git fetch> or C<git clone> to obtain the git branch
178 prepared by your sponsee,
179 and obtain any .origs mentioned by the sponsee
180 (to extract .origs committed with pristine-tar,
181 you can use origtargz(1),
182 or use "gbp clone --pristine-tar".)
183
184 Check the git commit ID of the sponsee's branch tip,
185 and the sha256sums of the .origs,
186 against the handoff email.
187
188 Confirm that the sponsee has not made
189 a debian/1.2.3-1 tag.
190 If they have,
191 it is best to ask them to delete it now,
192 as it can cause confusion later when dgit push produces its own tag.
193
194 Now you can check out the branch tip,
195 and do your substantive review.
196
197 =head2 Dealing with branches that want --quilt=
198
199 If your sponsee mentioned a C<--quilt>
200 option, and you don't want to grapple with their preferred tree format,
201 you can convert their tree into the standard dgit view:
202
203 =over 4
204
205     % dgit -wgf --quilt=foo --dgit-view-save=unquilted quilt-fixup
206     % git checkout unquilted
207
208 =back
209
210 You should check that what you're looking at is a descendant of
211 the sponsee's branch.
212
213 =head2 Some hints which may help the review
214
215 C<dgit fetch sid> will get you an up-to-date
216 C<refs/remotes/dgit/dgit/sid>
217 showing what's in the archive already.
218
219 C<dgit -wgf --damp-run push>
220 will check that dgit can build an appropriate source package.
221
222 There is no need to run debdiff.
223 dgit will not upload anything that doesn't unpack
224 to exactly the git commit you are pushing,
225 so you can rely on what you see in C<git diff>.
226
227 =head2 Doing the upload
228
229 When you have completed your source review,
230 and use
231 C<dgit -wgf [--quilt=...] sbuild -A -C>
232 or similar, to to the build, and then
233 C<dgit -wgf [--quilt=...] push>
234 to do the upload.
235
236 (If you switched to the quilt-cache dgit view,
237 B<do not> pass the --quilt or --gbp or --dpm option again.)
238
239 If this was the first upload done with dgit,
240 you may need to pass
241 C<--overwrite>
242 to dgit.
243
244
245 =head1 SPONSORING A NON-GIT-USING SPONSEE
246
247 This part is addressed to the sponsor:
248
249 If your sponsee does not use git,
250 you can still do your review with git,
251 and use dgit for the upload.
252
253 Your sponsee will provide you with a source package:
254 that is, a .dsc and the files it refers to.
255 Obtain these files, and check signatures as appropriate.
256 Then:
257
258 =over 4
259
260     % dgit clone PACKAGE
261     % cd PACKAGE
262     % dgit import-dsc /path/to/sponsee's.dsc +sponsee
263     % git checkout sponsee
264
265 =back
266
267 Or for an entirely new package:
268
269 =over 4
270
271     % mkdir PACKAGE
272     % cd PACKAGE
273     % git init
274     % dgit -pPACKAGE import-dsc /path/to/sponsee's.dsc +sponsee
275
276 =back
277
278 This will leave you looking at the sponsee's package,
279 formatted as a dgit branch.
280
281 When you have finished your review and your tests,
282 you can do the
283 dgit sbuild and
284 dgit push directly from the "sponsee" branch.
285
286 You will need to pass
287 C<--overwrite>
288 to dgit push for every successive upload.
289 This disables a safety catch which would normally spot
290 situations where changes are accidentally lost.
291 When your sponsee is sending you source packages -
292 perhaps multiple source pacakges with the same version number -
293 these safety catches are inevitably ineffective.
294
295 =head1 SEE ALSO
296
297 dgit(1), dgit(7), dgit-nmu-simple(7), dgit-maint-*(7)