1dgit-sponsorship(7) dgit dgit-sponsorship(7)
2
6 dgit-sponsorship - tutorial for Debian upload sponsorship, using git
7
9 This tutorial describes how a Debian sponsored contributor and a
10 sponsoring DD (or DM) can collaborate and publish using git.
11 The sponsor must be intending to use dgit for the upload. (If the
13 sponsor does not use dgit, it is not possible to properly publish a
14 sponsee's git branch.)
15 It is best if the sponsee also uses dgit; but also covered (later on)
17 is the case where the sponsee provides a proposed upload in source
18 package form, but the sponsor would like to work in git.
19 This tutorial does not provide a checklist for the sponsor's review.
21 Both contributors are expected to be familiar with Debian packaging and
22 Debian's processes, and with git.
23
25 This section is addressed to the sponsee:
26 General
28 You should prepare the package as if you were going to upload it with
29 "dgit push-source" or "dgit push" yourself.
30 For a straightforward NMU, consult dgit-nmu-simple(7).
32 If you are the (prospective) maintainer, you can adopt any suitable
34 (dgit-compatible) git workflow. The dgit-maint-*(7) tutorials describe
35 some of the possibilities.
36 Upload preparation
38 You should go through all of the steps a self-uploading maintainer
39 would do, including building for ad hoc tests, and checking via a
40 formal build (eg using "dgit sbuild") that the package builds on sid
41 (or the target release).
42 At the point where you would, if you were a DD, do the actual upload by
44 running dgit push, you hand off to your sponsor.
45 If you were going to use one of the "--quilt=" options to dgit, or
47 "dgit --gbp" or "dgit --dpm", you must specify that in your handoff
48 email - see below.
49 git+origs based handoff
51 The elements of the handoff consists of:
52 • The git branch.
54 • Any .orig tarballs which will be needed, or sample git-archive(1)
56 or gbp-buildpackage(1) command(s) to generate them.
57 • A sample dgit push command, containing any dgit --quilt=, --gbp or
59 --dpm option needed
60 • Plus of course all the usual information about the state of the
62 package, any caveats or areas you would like the sponsor to focus
63 their review, constraints about upload timing, etc.
64 If the handoff is done by email, the elements above should be a in a
66 single, signed, message. This could be an RFS submission against the
67 sponsorship-requests pseudo-package.
68 git branch
70 The sponsee should push their HEAD as a git branch to any suitable
72 git server. They can use their own git server; salsa is another
73 possibility.
74 The branch names used by the sponsee on their local machine, and on
76 the server, do not matter.
77 Instead, the sponsee should include the git commit id of their HEAD
79 in their handover email.
80 orig tarballs
82 If there are any .origs that are not in the archive already, the
84 sponsor will need them as part of the upload.
85 If the sponsee generated these tarballs with git-archive(1) or
87 gbp-buildpackage(1), they can simply include a sample invocation of
88 git-archive(1) or ensure that a suitable gbp.conf is present in the
89 source package to generate the tarball.
90 Otherwise, the simplest approach is to commit the orig tarballs
92 with pristine-tar(1), e.g.
93 % pristine-tar commit ../foo_1.2.3.orig.tar.xz upstream/1.2.3
95 and be sure to push the pristine-tar branch. If you are using
97 git-buildpackage(1), just pass --git-pristine-tar and
98 --git-pristine-tar-commit.
99 Alternatively, the sponsee can put them on a suitable webserver, or
101 attach to the e-mail, if they are small.
102 The sponsee should quote sha256sums of the .origs in their handoff
104 email, unless they supplied commands to generate them.
105 quilt options
107 Some workflows involve git branches which are not natively dgit-
109 compatible. Normally dgit will convert them as needed, during
110 push.
111 Supply a sample "dgit push" command including any "--gbp" (aka
113 "--quilt=gbp"), "--dpm" (aka "--quilt=dpm"), or other "--quilt="
114 option they need to use. e.g.
115 % dgit --gbp push
117
119 This part is addressed to the sponsor:
120 Receiving and validating the sponsorship request
122 You should check the signature on the email.
123 Use "git fetch" or "git clone" to obtain the git branch prepared by
125 your sponsee, and obtain any .origs mentioned by the sponsee (to
126 extract .origs committed with pristine-tar, you can use origtargz(1),
127 or use "gbp clone --pristine-tar".)
128 Check the git commit ID of the sponsee's branch tip, and the sha256sums
130 of the .origs, against the handoff email.
131 Now you can check out the branch tip, and do your substantive review.
133 Dealing with branches that want --quilt=
135 If your sponsee mentioned a "--quilt" option, and you don't want to
136 grapple with their preferred tree format, you can convert their tree
137 into the standard dgit view:
138 % dgit -wgf --quilt=foo --dgit-view-save=unquilted quilt-fixup
140 % git checkout unquilted
141 You should check that what you're looking at is a descendant of the
143 sponsee's branch.
144 Some hints which may help the review
146 "dgit fetch sid" will get you an up-to-date
147 "refs/remotes/dgit/dgit/sid" showing what's in the archive already.
148 "dgit -wgf --damp-run push-source" will check that dgit can build an
150 appropriate source package.
151 There is no need to run debdiff. dgit will not upload anything that
153 doesn't unpack to exactly the git commit you are pushing, so you can
154 rely on what you see in "git diff".
155 Doing the upload
157 When you have completed your source review, and use "dgit -wgf
158 [--quilt=...] sbuild -A -C" or similar, to to the build, and then "dgit
159 -wgf [--quilt=...] push-source" or "dgit -wgf [--quilt=...] push" to do
160 the upload.
161 Check whether the sponsee made a debian/version tag. If they did,
163 ensure you have their tag in the repository you are pushing from, or
164 pass "--no-dep14tag". This avoids identically named, non-identical
165 tags, which can be confusing.
166 (It is possible to upload from the quilt-cache dgit view. If you want
168 to do this, do not pass the "--quilt" or "--gbp" or "--dpm" options
169 again, and do pass "--no-dep14tag", since the debian/version tag should
170 go on the sponsee's branch.)
171 If this was the first upload done with dgit, you may need to pass
173 "--overwrite" to dgit.
174 Alternatively, if this was the first ever dgit push of the package, you
176 can pass "--deliberately-not-fast-forward" instead of "--overwrite".
177 This avoids introducing a new origin commit into the dgit view of the
178 sponsee's git history which is unnecessary and could be confusing.
179
181 This part is addressed to the sponsor:
182 If your sponsee does not use git, you can still do your review with
184 git, and use dgit for the upload.
185 Your sponsee will provide you with a source package: that is, a .dsc
187 and the files it refers to. Obtain these files, and check signatures
188 as appropriate. Then:
189 % dgit clone PACKAGE
191 % cd PACKAGE
192 % dgit import-dsc /path/to/sponsee's.dsc +sponsee
193 % git checkout sponsee
194 Or for an entirely new package:
196 % mkdir PACKAGE
198 % cd PACKAGE
199 % git init
200 % dgit -pPACKAGE import-dsc /path/to/sponsee's.dsc +sponsee
201 This will leave you looking at the sponsee's package, formatted as a
203 dgit branch.
204 When you have finished your review and your tests, you can do the dgit
206 sbuild and dgit push directly from the "sponsee" branch.
207 You will need to pass "--overwrite" to dgit push for every successive
209 upload. This disables a safety catch which would normally spot
210 situations where changes are accidentally lost. When your sponsee is
211 sending you source packages - perhaps multiple source packages with the
212 same version number - these safety catches are inevitably ineffective.
213
215 dgit(1), dgit(7), dgit-nmu-simple(7), dgit-maint-*(7)
216perl v5.34.0 Debian Project dgit-sponsorship(7)