1 # SOME DESCRIPTIVE TITLE
2 # Copyright (C) YEAR Free Software Foundation, Inc.
3 # This file is distributed under the same license as the PACKAGE package.
4 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
9 "Project-Id-Version: PACKAGE VERSION\n"
10 "POT-Creation-Date: 2019-03-01 16:59+0000\n"
11 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
12 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
13 "Language-Team: LANGUAGE <LL@li.org>\n"
16 "Content-Type: text/plain; charset=UTF-8\n"
17 "Content-Transfer-Encoding: 8bit\n"
20 #: ../dgit.1:3 ../dgit.7:2 ../dgit-user.7.pod:1 ../dgit-nmu-simple.7.pod:1
21 #: ../dgit-maint-native.7.pod:1 ../dgit-maint-merge.7.pod:1
22 #: ../dgit-maint-gbp.7.pod:1 ../dgit-maint-debrebase.7.pod:1
23 #: ../dgit-downstream-dsc.7.pod:1 ../dgit-sponsorship.7.pod:1
24 #: ../git-debrebase.1.pod:1 ../git-debrebase.5.pod:1
30 #: ../dgit.1:1253 ../dgit-downstream-dsc.7.pod:150
36 #: ../dgit.1:1267 ../dgit-downstream-dsc.7.pod:286
38 msgid "B<dgit-suite.>I<suite>B<.distro> I<distro>"
42 #: ../dgit.1:1320 ../dgit-downstream-dsc.7.pod:242
44 msgid "B<dgit-distro.>I<distro>B<.upload-host>"
48 #: ../dgit.1:1470 ../dgit.7:23 ../dgit-user.7.pod:447
49 #: ../dgit-nmu-simple.7.pod:137 ../dgit-maint-native.7.pod:126
50 #: ../dgit-maint-merge.7.pod:491 ../dgit-maint-gbp.7.pod:136
51 #: ../dgit-maint-debrebase.7.pod:747 ../dgit-downstream-dsc.7.pod:352
52 #: ../dgit-sponsorship.7.pod:321 ../git-debrebase.1.pod:619
53 #: ../git-debrebase.5.pod:678
59 #: ../dgit-user.7.pod:5 ../dgit-maint-native.7.pod:5
60 #: ../dgit-maint-merge.7.pod:5 ../dgit-maint-gbp.7.pod:5
61 #: ../dgit-maint-debrebase.7.pod:5 ../dgit-downstream-dsc.7.pod:5
62 #: ../git-debrebase.1.pod:10 ../git-debrebase.5.pod:5
67 #: ../dgit-downstream-dsc.7.pod:3
68 msgid "dgit-downstream-dsc - setting up dgit push for a new distro"
72 #: ../dgit-downstream-dsc.7.pod:7
74 "This document is aimed at downstreams of Debian. It explains how you can "
75 "publish your packages' source code both as traditional Debian source "
76 "packages, and as git branches, using B<dgit push>. Your users will be able "
77 "to get the source with B<dgit clone>, or with traditional tools such as "
82 #: ../dgit-downstream-dsc.7.pod:16
84 "Note that often it is unnecessary to publish traditional source packages. "
85 "Debian-format source packages can be complex, idiosyncratic and difficult to "
86 "work with. You should avoid them if you can. If you do not need to publish "
87 "source packages, you can work as a Debian downstream purely using git "
88 "branches, (using dgit to get the source from Debian in git form). You can "
89 "build binaries directly from git, and push package source code as a git "
90 "branch to an ordinary git server. See L<dgit-user(7)>."
94 #: ../dgit-downstream-dsc.7.pod:28
96 "Not every option is covered here. L<dgit(1)> has a mostly-complete list of "
97 "config options, although not always with useful descriptions."
101 #: ../dgit-downstream-dsc.7.pod:32
106 #: ../dgit-downstream-dsc.7.pod:34
107 msgid "You need to choose some names."
111 #: ../dgit-downstream-dsc.7.pod:38
112 msgid "I<distro> name"
116 #: ../dgit-downstream-dsc.7.pod:40
118 "dgit understands each thing it interacts with as a B<distro>. So in dgit "
119 "terms, you are setting up a distro."
123 #: ../dgit-downstream-dsc.7.pod:43
125 "You need a name for yourself (ie for your distro). The name will appear in "
126 "the git tags made by your tools, and in configuration settings. It must be "
127 "globally unique across all people and institutions who use dgit."
131 #: ../dgit-downstream-dsc.7.pod:49
133 "You could choose your organisation's domain name, or a part of it if you "
134 "think that is going to be very unique."
138 #: ../dgit-downstream-dsc.7.pod:52
140 "The distro name may contain ascii alphanumerics and B<. + ->, although B<-> "
141 "may be confusing and is probably best avoided. Try to avoid uppercase "
142 "letters (and underscore): you will be typing this name a lot."
146 #: ../dgit-downstream-dsc.7.pod:57
148 "For example, if you were the Free Software Foundation Europe (fsfe.org) you "
149 "might call your distro fsfe or fsfe.org. In the rest of this document we "
150 "will write I<distro> for your distro name."
154 #: ../dgit-downstream-dsc.7.pod:63
155 msgid "I<suite> names"
159 #: ../dgit-downstream-dsc.7.pod:65
161 "In dgit and Debian archive terminology, a B<suite> is a line of development, "
162 "and/or a Debian release. For example, at the time of writing, Debian has "
163 "suites like B<sid> aka B<unstable>, B<buster> aka B<testing>, and B<stretch> "
164 "aka B<stable>. There are also ancillary suites like B<stretch-security>."
168 #: ../dgit-downstream-dsc.7.pod:72
170 "If your releases align with Debian's releases, then your suites should "
171 "contain the Debian suite names. B<Do not> use just the Debian names. That "
172 "will cause confusion. Instead, prepend your organisation's name and a "
173 "hyphen. For example, FSFE might end up with suites like fsfe-stretch."
177 #: ../dgit-downstream-dsc.7.pod:79
179 "Suite names end up in git ref and branch names, and on dgit command lines. "
180 "Suite names can contain alphanumerics and C<->. Other characters may work "
181 "but are not recommended."
185 #: ../dgit-downstream-dsc.7.pod:86
190 #: ../dgit-downstream-dsc.7.pod:88
191 msgid "You will need to run two parallel services:"
195 #: ../dgit-downstream-dsc.7.pod:92
200 #: ../dgit-downstream-dsc.7.pod:94
201 msgid "This will hold the git branches accessed by dgit."
205 #: ../dgit-downstream-dsc.7.pod:96
207 "Everyone who will use dgit push needs to be able to update B<refs/dgit/"
208 ">I<suite> (note, not B<refs/heads/dgit/>I<suite>) on that server, and to "
209 "make tags I<distro>B</>I<version> and B<archive/>I<distro>B</>I<version>. "
210 "Normally this would be done over ssh."
214 #: ../dgit-downstream-dsc.7.pod:103
216 "The server may host other branches and tags too. So this might be your "
217 "ordinary git server, or an instance of a git hosting system."
221 #: ../dgit-downstream-dsc.7.pod:107
223 "Everyone who obtains one of your source packages, or who will run B<dgit "
224 "clone> and B<dgit fetch>, needs to have at least read access to the git "
225 "server. Ideally everything would be published via the git smart https "
230 #: ../dgit-downstream-dsc.7.pod:113
232 "The git server name, and public git url structure, should be chosen so they "
233 "will not need to change in the future. Best is to give the git server a DNS "
238 #: ../dgit-downstream-dsc.7.pod:117
240 "Debian's dgit git server has special access control rules, implemented in "
241 "B<dgit-repos-server> and B<dgit-repos-policy-debian> in the package B<dgit-"
242 "infrastructure>. but in most installations this is not needed. If there is "
243 "no or little distinction between (i) developers who are entitled to upload "
244 "(push) and (ii) repository administrators, then it is sufficient to provide "
245 "a git server with a unix account for each user who will be pushing, perhaps "
246 "using ssh restricted commands."
250 #: ../dgit-downstream-dsc.7.pod:128
251 msgid "Debian-format archive (repository)"
255 #: ../dgit-downstream-dsc.7.pod:130
257 "This holds the source packages. You will probably use the same archive to "
258 "host your binaries, and point your B<apt> at it."
262 #: ../dgit-downstream-dsc.7.pod:134
263 msgid "dgit uses the term B<archive> for this."
267 #: ../dgit-downstream-dsc.7.pod:136
269 "There are a variety of tools for creating and managing a Debian-format "
270 "archive. In this document we will assume you are using B<reprepro>."
274 #: ../dgit-downstream-dsc.7.pod:140
276 "Setting up reprepro is not covered in this tutorial. Instead, we assume you "
277 "already have reprepro working."
281 #: ../dgit-downstream-dsc.7.pod:143
283 "You should also write appropriate dput configuration, since dgit uses dput "
284 "to upload packages to the archive. This will involve choosing a dput host "
285 "name. That's probably your distro name, I<distro>."
289 #: ../dgit-downstream-dsc.7.pod:152
291 "When you have all of the above set up, you are ready to explain to dgit how "
292 "to access your systems."
296 #: ../dgit-downstream-dsc.7.pod:155
298 "dgit is configured via git's configuration system, so this is done with git "
299 "configuration. See L<git-config(1)>."
303 #: ../dgit-downstream-dsc.7.pod:159
305 "Below, each heading is one or more git config keys. B<bold> is literal text "
306 "and I<italics> is things that vary. In the descriptions of the effects of "
307 "config settings, we refer to the config values C<like this>."
311 #: ../dgit-downstream-dsc.7.pod:167
312 msgid "B<dgit-distro.>I<distro>B<.git-url>, B<.git-url-suffix>"
316 #: ../dgit-downstream-dsc.7.pod:169
318 "Specify the publicly accessible git URLs for your dgit git server. The urls "
319 "generated are C<git-url>B</>I<package>C<git-url-suffix>"
323 #: ../dgit-downstream-dsc.7.pod:173
325 "The url should be stable, and publicly accessible, because its name is "
326 "published in .dsc files. (Note that if you make modified versions of "
327 "packages from Debian, the copyleft licences used for Free Software often "
328 "require you to permit your users, employees, and downstreams to further "
329 "distribute your modified source code.)"
333 #: ../dgit-downstream-dsc.7.pod:181
334 msgid "B<dgit-distro.>I<distro>B</push.git-host>"
338 #: ../dgit-downstream-dsc.7.pod:183
339 msgid "The domain name of your git server's ssh interface."
343 #: ../dgit-downstream-dsc.7.pod:185
345 "B<dgit-distro.>I<distro>B</push.git-user-force> B<dgit-distro.>I<distro>B</"
350 #: ../dgit-downstream-dsc.7.pod:187
352 "Some git hosting systems expect everyone to connect over ssh as the same "
353 "user, often B<git>. If this is the case, set C<git-user-force> to that user."
357 #: ../dgit-downstream-dsc.7.pod:191
359 "If you have a normal git over ssh arrangement, where people ssh as "
360 "themselves, leave C<git-user-force> unset. If a user wishes to override the "
361 "username (for example, if their local username is not the same as on the "
362 "server) they can set C<username>."
366 #: ../dgit-downstream-dsc.7.pod:198
367 msgid "B<dgit-distro.>I<distro>B</push.git-url>"
371 #: ../dgit-downstream-dsc.7.pod:200
373 "Set this to the empty string. This will arrange that push accesses to the "
374 "ssh server will use C</push.git-host>, etc."
378 #: ../dgit-downstream-dsc.7.pod:204
379 msgid "B<dgit-distro.>I<distro>B</push.git-proto> B<git+ssh://>"
383 #: ../dgit-downstream-dsc.7.pod:206
384 msgid "C<dgit-distro.>I<distro>B</push.git-path>"
388 #: ../dgit-downstream-dsc.7.pod:208
390 "The path to your repositories. dgit push will try to push to C<git-"
391 "proto>[C<git-user-force>|C<username>B<@>]C<git-path>B</>I<package>B<.git>"
395 #: ../dgit-downstream-dsc.7.pod:212
396 msgid "B<dgit-distro.>I<distro>B<.git-check>, B<.git-check-suffix>"
400 #: ../dgit-downstream-dsc.7.pod:214
402 "dgit clone needs to be able to tell whether there is yet a git repository "
403 "for a particular package."
407 #: ../dgit-downstream-dsc.7.pod:217
409 "If you always have a git repository for every package in your archive, "
410 "perhaps because you never use dput/dupload, and always dgit push, set C<git-"
415 #: ../dgit-downstream-dsc.7.pod:221
417 "Otherwise, set C<git-check> to a url prefix - ideally, https. dgit clone "
418 "will try to fetch C<git-check>B</>I<package>C<git-check-suffix> and expect "
419 "to get either some successful fetch (it doesn't matter what) or a file not "
420 "found error (http 404 status code). Other outcomes are fatal errors."
424 #: ../dgit-downstream-dsc.7.pod:228
426 "If your git server runs cgit, then you can set C<git-check> to the same as "
427 "C<git-url>, and C<git-check-suffix> to B</info/refs>."
431 #: ../dgit-downstream-dsc.7.pod:232
432 msgid "B<dgit-distro.>I<distro>B</push.git-check>, B</push.git-create>"
436 #: ../dgit-downstream-dsc.7.pod:234
437 msgid "dgit push also needs to be able to check whether the repo exists."
441 #: ../dgit-downstream-dsc.7.pod:236
443 "You can set both of these to B<ssh-cmd>, which will use an ssh shell command "
444 "to test repository existence. Or leave them unset, and dgit push will use "
445 "the readonly details. If repositories are created automatically on push, "
446 "somehow, you can set C<git-create> to B<true>."
450 #: ../dgit-downstream-dsc.7.pod:244
451 msgid "What I<host> value to pass to dput, to upload."
455 #: ../dgit-downstream-dsc.7.pod:246
457 "This is a nickname, not the real host name. You need to provide everyone "
458 "who will push with an appropriate dput configuration. See L<dput.cf(5)>."
462 #: ../dgit-downstream-dsc.7.pod:251
463 msgid "A good nickname for your upload host is your distro name I<distro>."
467 #: ../dgit-downstream-dsc.7.pod:253
468 msgid "B<dgit-distro.>I<distro>B<.mirror>"
472 #: ../dgit-downstream-dsc.7.pod:255
474 "Set this to the url of your source package archive. This is the same string "
475 "as appears in the 2nd field of each B<sources.list> entry."
479 #: ../dgit-downstream-dsc.7.pod:259
480 msgid "B<dgit-distro.>I<distro>B<.archive-query>, B<.archive-query-url>"
484 #: ../dgit-downstream-dsc.7.pod:261
486 "If you have a smallish distro, set C<archive-query> to B<aptget:> (with a "
491 #: ../dgit-downstream-dsc.7.pod:264
493 "If your distro is large (eg, if it contains a substantial fraction of "
494 "Debian) then this will not be very efficient: with this setting, dgit often "
495 "needs to download and update Sources files."
499 #: ../dgit-downstream-dsc.7.pod:270
501 "For large distros, it is better to implement the Debian archive ftpmaster "
502 "API. See L<https://api.ftp-master.debian.org/>, and set C<archive-query> to "
503 "B<ftpmasterapi:> (with a colon) and C<archive-query-url> to your API base "
504 "URL. dgit uses these queries: B<suites>, B<dsc_in_suite/>I<isuite>B</"
505 ">I<package> and B<file_in_archive/>I<pat> (so you need not implement "
510 #: ../dgit-downstream-dsc.7.pod:281
512 "Alternatively, if your system supports the rmadison protocol, you can set "
513 "C<archive-query> to B<madison:>[I<madison-distro>]. dgit will invoke "
514 "B<rmadison> -uI<madison-distro>."
518 #: ../dgit-downstream-dsc.7.pod:288
520 "Set this for every one of your suites. You will have to update this when "
521 "new suites are created. If you forget, your users can explicitly specify B<-"
522 "d> I<distro> to dgit."
526 #: ../dgit-downstream-dsc.7.pod:295
527 msgid "TEMPLATE GIT REPOSITORY"
531 #: ../dgit-downstream-dsc.7.pod:297
533 "When dgit push is used for I<package> for the first time, it must create a "
534 "git repository on the git server."
538 #: ../dgit-downstream-dsc.7.pod:300
540 "If C<git-create> is set to B<ssh-cmd>, dgit will use the user's shell access "
541 "to the server to B<cp -a _template.git> I<package>B<.git>. So you should "
542 "create B<_template.git> with suitable contents."
546 #: ../dgit-downstream-dsc.7.pod:305
548 "Note that the ssh rune invoked by dgit does not do any locking. So if two "
549 "people dgit push the same package at the same time, there will be lossage. "
550 "Either don't do that, or set up B<dgit-repos-server>."
554 #: ../dgit-downstream-dsc.7.pod:310
559 #: ../dgit-downstream-dsc.7.pod:312
561 "When a user who can push runs dgit, dgit uses ssh to access the git server."
565 #: ../dgit-downstream-dsc.7.pod:315
567 "To make use of ssh restricted command easier, and for the benefit of dgit-"
568 "repos-server, dgit's ssh commands each start with a parseable commentish "
573 #: ../dgit-downstream-dsc.7.pod:320
574 msgid "The ssh commands used by dgit are these:"
578 #: ../dgit-downstream-dsc.7.pod:324
579 msgid "B<: dgit> I<distro> B<git-check> I<package> B<;>..."
583 #: ../dgit-downstream-dsc.7.pod:326
585 "Test whether I<package> has a git repo on the server already. Should print "
586 "B<0> or B<1> and a newline, and exit status zero in either case. The rest "
587 "of the command, after B<;>, is a shell implementation of this test. Used "
588 "when C<git-check> is set to B<ssh-cmd>."
592 #: ../dgit-downstream-dsc.7.pod:333
593 msgid "B<: dgit> I<distro> B<git-create> I<package> B<;>..."
597 #: ../dgit-downstream-dsc.7.pod:335
599 "Create the git repository for I<package> on the server. See L</TEMPLATE GIT "
600 "REPOSITORY>, above. The rest of the command is an appropriate invocation of "
601 "cd and cp. Used when C<git-create> is set to B<ssh-cmd>."
605 #: ../dgit-downstream-dsc.7.pod:340
606 msgid "B<git-receive-pack>..., B<git-upload-pack>..."
610 #: ../dgit-downstream-dsc.7.pod:342
612 "dgit invokes git to access the repository; git then runs these commands. "
613 "Note that dgit push will first do a git fetch over ssh, so you must provide "
614 "upload-pack as well as receive-pack."
618 #: ../dgit-downstream-dsc.7.pod:349
619 msgid "(There are also other ssh commands which are historical or obscure.)"
623 #: ../dgit-downstream-dsc.7.pod:354