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