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