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-source> or 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 salsa 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-source>
 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-source>
 238 or
 239 C<dgit -wgf [--quilt=...] push>
 240 to do the upload.
 241
 242 Check whether the sponsee made a debian/I<version> tag.
 243 If they did,
 244 ensure you have their tag in the repository you are pushing from,
 245 or pass C<--no-dep14tag>.
 246 This avoids identically named, non-identical tags,
 247 which can be confusing.
 248
 249 (It is possible to upload from
 250 the quilt-cache dgit view.
 251 If you want to do this,
 252 B<do not> pass the C<--quilt> or C<--gbp> or C<--dpm> options again,
 253 and B<do> pass C<--no-dep14tag>,
 254 since the debian/I<version> tag
 255 should go on the sponsee's branch.)
 256
 257 If this was the first upload done with dgit,
 258 you may need to pass
 259 C<--overwrite>
 260 to dgit.
 261
 262 Alternatively,
 263 if this was the first ever dgit push of the package,
 264 you can pass C<--deliberately-not-fast-forward>
 265 instead of C<--overwrite>.
 266 This avoids introducing a new origin commit
 267 into the dgit view of
 268 the sponsee's git history
 269 which is unnecessary and could be confusing.
 270
 271 =head1 SPONSORING A NON-GIT-USING SPONSEE
 272
 273 This part is addressed to the sponsor:
 274
 275 If your sponsee does not use git,
 276 you can still do your review with git,
 277 and use dgit for the upload.
 278
 279 Your sponsee will provide you with a source package:
 280 that is, a .dsc and the files it refers to.
 281 Obtain these files, and check signatures as appropriate.
 282 Then:
 283
 284 =over 4
 285
 286     % dgit clone PACKAGE
 287     % cd PACKAGE
 288     % dgit import-dsc /path/to/sponsee's.dsc +sponsee
 289     % git checkout sponsee
 290
 291 =back
 292
 293 Or for an entirely new package:
 294
 295 =over 4
 296
 297     % mkdir PACKAGE
 298     % cd PACKAGE
 299     % git init
 300     % dgit -pPACKAGE import-dsc /path/to/sponsee's.dsc +sponsee
 301
 302 =back
 303
 304 This will leave you looking at the sponsee's package,
 305 formatted as a dgit branch.
 306
 307 When you have finished your review and your tests,
 308 you can do the
 309 dgit sbuild and
 310 dgit push directly from the "sponsee" branch.
 311
 312 You will need to pass
 313 C<--overwrite>
 314 to dgit push for every successive upload.
 315 This disables a safety catch which would normally spot
 316 situations where changes are accidentally lost.
 317 When your sponsee is sending you source packages -
 318 perhaps multiple source pacakges with the same version number -
 319 these safety catches are inevitably ineffective.
 320
 321 =head1 SEE ALSO
 322
 323 dgit(1), dgit(7), dgit-nmu-simple(7), dgit-maint-*(7)