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 Now you can check out the branch tip,
 189 and do your substantive review.
 190
 191 =head2 Dealing with branches that want --quilt=
 192
 193 If your sponsee mentioned a C<--quilt>
 194 option, and you don't want to grapple with their preferred tree format,
 195 you can convert their tree into the standard dgit view:
 196
 197 =over 4
 198
 199     % dgit -wgf quilt-fixup
 200     [ Watch for a message about split brain, and if so: ]
 201     % git checkout -b dgit-view-for-review refs/dgit-intern/quilt-cache
 202
 203 =back
 204
 205 You should check that what you're looking at is a descendant of
 206 the sponsee's branch.
 207
 208 =head2 Some hints which may help the review
 209
 210 C<dgit fetch sid> will get you an up-to-date
 211 C<refs/remotes/dgit/dgit/sid>
 212 showing what's in the archive already.
 213
 214 C<dgit -wgf --damp-run push>
 215 will check that dgit can build an appropriate source package.
 216
 217 There is no need to run debdiff.
 218 dgit will not upload anything that doesn't unpack
 219 to exactly the git commit you are pushing,
 220 so you can rely on what you see in C<git diff>.
 221
 222 =head2 Doing the upload
 223
 224 When you have completed your source review,
 225 and use
 226 C<dgit -wgf [--quilt=...] sbuild -A -C>
 227 or similar, to to the build, and then
 228 C<dgit -wgf [--quilt=...] push>
 229 to do the upload.
 230
 231 (If you switched to the quilt-cache dgit view,
 232 B<do not> pass the --quilt or --gbp or --dpm option again.)
 233
 234 If this was the first upload done with dgit,
 235 you may need to pass
 236 C<--overwrite>
 237 to dgit.
 238
 239
 240 =head1 SPONSORING A NON-GIT-USING SPONSEE
 241
 242 This part is addressed to the sponsor:
 243
 244 If your sponsee does not use git,
 245 you can still do your review with git,
 246 and use dgit for the upload.
 247
 248 Your sponsee will provide you with a source package:
 249 that is, a .dsc and the files it refers to.
 250 Obtain these files, and check signatures as appropriate.
 251 Then:
 252
 253 =over 4
 254
 255     % dgit clone PACKAGE
 256     % cd PACKAGE
 257     % dgit import-dsc /path/to/sponsee's.dsc +sponsee
 258     % git checkout sponsee
 259
 260 =back
 261
 262 This will leave you looking at the sponsee's package,
 263 formatted as a dgit branch.
 264
 265 When you have finished your review and your tests,
 266 you can do the
 267 dgit sbuild and
 268 dgit push directly from the "sponsee" branch.
 269
 270 You will need to pass
 271 C<--overwrite>
 272 to dgit push for every successive upload.
 273 This disables a safety catch which would normally spot
 274 situations where changes are accidentally lost.
 275 When your sponsee is sending you source packages -
 276 perhaps multiple source pacakges with the same version number -
 277 these safety catches are inevitably ineffective.
 278
 279 =head1 SEE ALSO
 280
 281 dgit(1), dgit(7), dgit-nmu-simple(7), dgit-maint-*(7)