chiark / gitweb /
i18n: i18n-diff-auditor: fix striang (de)concatenation
[dgit.git] / dgit-downstream-dsc.7.pod
1 =head1 NAME
2
3 dgit-downstream-dsc - setting up dgit push for a new distro
4
5 =head1 INTRODUCTION
6
7 This document is aimed at downstreams of Debian.
8 It explains how you can
9 publish your packages' source code
10 both as traditional Debian source packages,
11 and as git branches,
12 using B<dgit push>.
13 Your users will be able to get the source with B<dgit clone>,
14 or with traditional tools such as B<apt-get source>.
15
16 Note that often it is unnecessary to
17 publish traditional source packages.
18 Debian-format source packages can be complex,
19 idiosyncratic and difficult to work with.
20 You should avoid them if you can.
21 If you do not need to publish source packages,
22 you can work as a Debian downstream purely using git branches,
23 (using dgit to get the source from Debian in git form).
24 You can build binaries directly from git,
25 and push package source code as a git branch to an ordinary git server.
26 See L<dgit-user(7)>.
27
28 Not every option is covered here.
29 L<dgit(1)> has a mostly-complete list
30 of config options, although not always with useful descriptions.
31
32 =head1 NAMES
33
34 You need to choose some names.
35
36 =over
37
38 =item I<distro> name
39
40 dgit understands each thing it interacts with as a B<distro>.
41 So in dgit terms, you are setting up a distro.
42
43 You need a name for yourself (ie for your distro).
44 The name will appear in the git tags made by your tools,
45 and in configuration settings.
46 It must be globally unique across
47 all people and institutions who use dgit.
48
49 You could choose your organisation's domain name,
50 or a part of it if you think that is going to be very unique.
51
52 The distro name may contain ascii alphanumerics and B<. + ->,
53 although B<-> may be confusing and is probably best avoided.
54 Try to avoid uppercase letters (and underscore):
55 you will be typing this name a lot.
56
57 For example,
58 if you were the Free Software Foundation Europe (fsfe.org)
59 you might call your distro fsfe or fsfe.org.
60 In the rest of this document we will write
61 I<distro> for your distro name.
62
63 =item I<suite> names
64
65 In dgit and Debian archive terminology, a B<suite> is a line of
66 development, and/or a Debian release.
67 For example, at the time of writing, Debian has suites like
68 B<sid> aka B<unstable>, B<buster> aka B<testing>,
69 and B<stretch> aka B<stable>.
70 There are also ancillary suites like B<stretch-security>.
71
72 If your releases align with Debian's releases,
73 then your suites should contain the Debian suite names.
74 B<Do not> use just the Debian names.
75 That will cause confusion.
76 Instead, prepend your organisation's name and a hyphen.
77 For example, FSFE might end up with suites like fsfe-stretch.
78
79 Suite names end up in git ref and branch names,
80 and on dgit command lines.
81 Suite names can contain alphanumerics and C<->.
82 Other characters may work but are not recommended.
83
84 =back
85
86 =head1 SERVICES
87
88 You will need to run two parallel services:
89
90 =over
91
92 =item git server
93
94 This will hold the git branches accessed by dgit.
95
96 Everyone who will use dgit push needs to be able to update
97 B<refs/dgit/>I<suite>
98 (note, not B<refs/heads/dgit/>I<suite>) on that server,
99 and to make tags
100 I<distro>B</>I<version> and B<archive/>I<distro>B</>I<version>.
101 Normally this would be done over ssh.
102
103 The server may host other branches and tags too.
104 So this might be your ordinary git server,
105 or an instance of a git hosting system.
106
107 Everyone who obtains one of your source packages,
108 or who will run B<dgit clone> and  B<dgit fetch>,
109 needs to have at least read access to the git server.
110 Ideally everything would be published
111 via the git smart https protocol.
112
113 The git server name, and public git url structure,
114 should be chosen so they will not need to change in the future.
115 Best is to give the git server a DNS name of its own.
116
117 Debian's dgit git server has special access control rules,
118 implemented in B<dgit-repos-server> and B<dgit-repos-policy-debian>
119 in the package B<dgit-infrastructure>.
120 but in most installations this is not needed.
121 If there is no or little distinction between
122 (i) developers who are entitled to upload (push) and
123 (ii) repository administrators,
124 then a it is sufficient to provide a
125 git server with a unix account for each user who will pushing,
126 perhaps using ssh restricted commands.
127
128 =item Debian-format archive (repository)
129
130 This holds the source packages.
131 You will probably use the same archive to host your binaries,
132 and point your B<apt> at it.
133
134 dgit uses the term B<archive> for this.
135
136 There are a variety of tools for
137 creating and managing a Debian-format archive.
138 In this document we will assume you are using B<reprepro>.
139
140 Setting up reprepro is not covered in this tutorial.
141 Instead, we assume you already have reprepro working.
142
143 You should also write appropriate dput configuration,
144 since dgit uses dput to upload packages to the archive.
145 This will involve choosing a dput host name.
146 That's probably your distro name, I<distro>.
147
148 =back
149
150 =head1 CONFIGURATION
151
152 When you have all of the above set up,
153 you are ready to explain to dgit how to access your systems.
154
155 dgit is configured via git's configuration system,
156 so this is done with git configuration.
157 See L<git-config(1)>.
158
159 Below, each heading is one or more git config keys.
160 B<bold> is literal text and I<italics>
161 is things that vary.
162 In the descriptions of the effects of config settings,
163 we refer to the config values C<like this>.
164
165 =over
166
167 =item B<dgit-distro.>I<distro>B<.git-url>, B<.git-url-suffix>
168
169 Specify the publicly accessible git URLs for your
170 dgit git server.  The urls generated are
171 C<git-url>B</>I<package>C<git-url-suffix>
172
173 The url should be stable,
174 and publicly accessible,
175 because its name is published in .dsc files.
176 (Note that if you make modified versions of packages from Debian,
177 the copyleft licences used for Free Software
178 often require you to permit your users, employees, and downstreams
179 to further distribute your modified source code.)
180
181 =item B<dgit-distro.>I<distro>B</push.git-host>
182
183 The domain name of your git server's ssh interface.
184
185 =item B<dgit-distro.>I<distro>B</push.git-user-force> B<dgit-distro.>I<distro>B</push.username>
186
187 Some git hosting systems expect everyone to
188 connect over ssh as the same user, often B<git>.
189 If this is the case, set C<git-user-force> to that user.
190
191 If you have a normal git over ssh arrangement,
192 where people ssh as themselves,
193 leave C<git-user-force> unset.
194 If a user wishes to override the username
195 (for example, if their local username is not the same as on the server)
196 they can set C<username>.
197
198 =item B<dgit-distro.>I<distro>B</push.git-url>
199
200 Set this to the empty string.
201 This will arrange that push accesses to the ssh server will use
202 C</push.git-host>, etc.
203
204 =item B<dgit-distro.>I<distro>B</push.git-proto> B<git+ssh://>
205
206 =item C<dgit-distro.>I<distro>B</push.git-path>
207
208 The path to your repositories.
209 dgit push will try to push to
210 C<git-proto>[C<git-user-force>|C<username>B<@>]C<git-path>B</>I<package>B<.git>
211
212 =item B<dgit-distro.>I<distro>B<.git-check>, B<.git-check-suffix>
213
214 dgit clone needs to be able to tell whether there is
215 yet a git repository for a particular package.
216
217 If you always have a git repository for every package in your archive,
218 perhaps because you never use dput/dupload, and always dgit push,
219 Set C<git-check> to B<true>.
220
221 Otherwise, set C<git-check> to a url prefix - ideally, https.
222 dgit clone will try to fetch
223 C<git-check>B</>I<package>C<git-check-suffix>
224 and expect to get either some successful fetch (it doesn't matter what)
225 or a file not found error (http 404 status code).
226 Other outcomes are fatal errors.
227
228 If your git server runs cgit,
229 then you can set C<git-check> to the same as C<git-url>,
230 and C<git-check-suffix> to B</info/refs>.
231
232 =item B<dgit-distro.>I<distro>B</push.git-check>, B</push.git-create>
233
234 dgit push also needs to be able to check whether the repo exists.
235
236 You can set both of these to B<ssh-cmd>,
237 which will use an ssh shell command to test repository existence.
238 Or leave them unset, and dgit push will use the readonly details.
239 If repositories are created automatically on push, somehow,
240 you can set C<git-create> to B<true>.
241
242 =item B<dgit-distro.>I<distro>B<.upload-host>
243
244 What I<host> value to pass to dput, to upload.
245
246 This is a nickname, not the real host name.
247 You need to provide everyone who will push with an appropriate
248 dput configuration.
249 See L<dput.cf(5)>.
250
251 A good nickname for your upload host is your distro name I<distro>.
252
253 =item B<dgit-distro.>I<distro>B<.mirror>
254
255 Set this to the url of your source package archive.
256 This is the same string as appears
257 in the 2nd field of each B<sources.list> entry.
258
259 =item B<dgit-distro.>I<distro>B<.archive-query>, B<.archive-query-url>
260
261 If you have a smallish distro,
262 set C<archive-query> to B<aptget:> (with a colon).
263
264 If your distro is large
265 (eg, if it contains a substantial fraction of Debian)
266 then this will not be very efficient:
267 with this setting,
268 dgit often needs to download and update Sources files.
269
270 For large distros,
271 it is better to implement the Debian archive ftpmaster API.
272 See L<https://api.ftp-master.debian.org/>,
273 and set C<archive-query> to B<ftpmasterapi:> (with a colon)
274 and C<archive-query-url> to your API base URL.
275 dgit uses these queries:
276 B<suites>,
277 B<dsc_in_suite/>I<isuite>B</>I<package> and
278 B<file_in_archive/>I<pat>
279 (so you need not implement anything else).
280
281 Alternatively,
282 if your system supports the rmadison protocol,
283 you can set C<archive-query> to B<madison:>[I<madison-distro>].
284 dgit will invoke B<rmadison> -uI<madison-distro>.
285
286 =item B<dgit-suite.>I<suite>B<.distro> I<distro>
287
288 Set this for every one of your suites.
289 You will have to update this when new suites are created.
290 If you forget, your users can explicitly specify B<-d> I<distro>
291 to dgit.
292
293 =back
294
295 =head1 TEMPLATE GIT REPOSITORY
296
297 When dgit push is used for I<package> for the first time,
298 it must create a git repository on the git server.
299
300 If C<git-create> is set to B<ssh-cmd>, 
301 dgit will use the user's shell access to the server to
302 B<cp -a _template.git> I<package>B<.git>.
303 So you should create B<_template.git> with suitable contents.
304
305 Note that the ssh rune invoked by dgit does not do any locking.
306 So if two people dgit push the same package at the same time,
307 there will be lossage.
308 Either don't do that, or set up B<dgit-repos-server>.
309
310 =head1 SSH COMMANDS
311
312 When a user who can push runs dgit,
313 dgit uses ssh to access the git server.
314
315 To make ssh restricted command easier,
316 and for the benefit of dgit-repos-server,
317 dgit's ssh commands
318 each start with a parseable commentish rune.
319
320 The ssh commands used by dgit are these:
321
322 =over
323
324 =item B<: dgit> I<distro> B<git-check> I<package> B<;>...
325
326 Test whether I<package> has a git repo on the server already.
327 Should print B<0> or B<1> and a newline,
328 and exit status zero in either case.
329 The rest of the command, after B<;>,
330 is a shell implementation of this test.
331 Used when C<git-check> is set to B<ssh-cmd>.
332
333 =item B<: dgit> I<distro> B<git-create> I<package> B<;>...
334
335 Create the git repository for I<package> on the server.
336 See L</TEMPLATE GIT REPOSITORY>, above.
337 The rest of the command is an appropriate invocation of cd and cp.
338 Used when C<git-create> is set to B<ssh-cmd>.
339
340 =item B<git-receive-pack>..., B<git-upload-pack>...
341
342 dgit invokes git to access the repository;
343 git then runs these commands.
344 Note that dgit push will first do a git fetch over ssh,
345 so you must provide upload-pack as well as receive-pack.
346
347 =back
348
349 (There are also other ssh commands
350 which are historical or obscure.)
351
352 =head1 SEE ALSO
353
354 dgit(1)