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