diff options
-rw-r--r-- | .gitignore | 1 | ||||
-rw-r--r-- | Makefile | 1 | ||||
-rw-r--r-- | debian/changelog | 1 | ||||
-rw-r--r-- | dgit-downstream-dsc.7.pod | 354 | ||||
-rw-r--r-- | dgit.1 | 1 |
5 files changed, 358 insertions, 0 deletions
@@ -14,6 +14,7 @@ dgit-maint-merge.7 dgit-maint-gbp.7 dgit-maint-debrebase.7 dgit-sponsorship.7 +dgit-downstream-dsc.7 git-debrebase.1 git-debrebase.5 substituted @@ -41,6 +41,7 @@ MAN7PAGES=dgit.7 \ dgit-maint-native.7 \ dgit-maint-merge.7 dgit-maint-gbp.7 \ dgit-maint-debrebase.7 \ + dgit-downstream-dsc.7 \ dgit-sponsorship.7 TXTDOCS=README.dsc-import diff --git a/debian/changelog b/debian/changelog index 6a992d2..6f72c5e 100644 --- a/debian/changelog +++ b/debian/changelog @@ -7,6 +7,7 @@ dgit (5.9~) unstable; urgency=medium the ff pseudomerge into -fdiverged. Related to #903132. * git-debrebase, Dgit.pm, git: some internal reorganisation to support git-debrebase changes. + * dgit-downstream-dsc(7): New manpage. Closes:#842643,#851194. -- diff --git a/dgit-downstream-dsc.7.pod b/dgit-downstream-dsc.7.pod new file mode 100644 index 0000000..fcbce05 --- /dev/null +++ b/dgit-downstream-dsc.7.pod @@ -0,0 +1,354 @@ +=head1 NAME + +dgit-downstream-dsc - setting up dgit push for a new distro + +=head1 INTRODUCTION + +This document is aimed at downstreams of Debian. +It explains how you can +publish your packages' source code +both as traditional Debian source packages, +and as git branches, +using B<dgit push>. +Your users will be able to get the source with B<dgit clone>, +or with traditional tools such as B<apt-get source>. + +Note that often it is unnecessary to +publish traditional source packages. +Debian-format source packages can be complex, +idiosyncratic and difficult to work with. +You should avoid them if you can. +If you do not need to publish source packages, +you can work as a Debian downstream purely using git branches, +(using dgit to get the source from Debian in git form). +You can build binaries directly from git, +and push package source code as a git branch to an ordinary git server. +See L<dgit-user(7)>. + +Not every option is covered here. +L<dgit(1)> has a mostly-complete list +of config options, although not always with useful descriptions. + +=head1 NAMES + +You need to choose some names. + +=over + +=item I<distro> name + +dgit understands each thing it interacts with as a B<distro>. +So in dgit terms, you are setting up a distro. + +You need a name for yourself (ie for your distro). +The name will appear in the git tags made by your tools, +and in configuration settings. +It must be globally unique across +all people and institutions who use dgit. + +You could choose your organisation's domain name, +or a part of it if you think that is going to be very unique. + +The distro name may contain ascii alphanumerics and B<. + ->, +although B<-> may be confusing and is probably best avoided. +Try to avoid uppercase letters (and underscore): +you will be typing this name a lot. + +For example, +if you were the Free Software Foundation Europe (fsfe.org) +you might call your distro fsfe or fsfe.org. +In the rest of this document we will write +I<distro> for your distro name. + +=item I<suite> names + +In dgit and Debian archive terminology, a B<suite> is a line of +development, and/or a Debian release. +For example, at the time of writing, Debian has suites like +B<sid> aka B<unstable>, B<buster> aka B<testing>, +and B<stretch> aka B<stable>. +There are also ancillary suites like B<stretch-security>. + +If your releases align with Debian's releases, +then your suites should contain the Debian suite names. +B<Do not> use just the Debian names. +That will cause confusion. +Instead, prepend your organisation's name and a hyphen. +For example, FSFE might end up with suites like fsfe-stretch. + +Suite names end up in git ref and branch names, +and on dgit command lines. +Suite names can contain alphanumerics and C<->. +Other characters may work but are not recommended. + +=back + +=head1 SERVICES + +You will need to run two parallel services: + +=over + +=item git server + +This will hold the git branches accessed by dgit. + +Everyone who will use dgit push needs to be able to update +B<refs/dgit/>I<suite> +(note, not B<refs/heads/dgit/>I<suite>) on that server, +and to make tags +I<distro>B</>I<version> and B<archive/>I<distro>B</>I<version>. +Normally this would be done over ssh. + +The server may host other branches and tags too. +So this might be your ordinary git server, +or an instance of a git hosting system. + +Everyone who obtains one of your source packages, +or who will run B<dgit clone> and B<dgit fetch>, +needs to have at least read access to the git server. +Ideally everything would be published +via the git smart https protocol. + +The git server name, and public git url structure, +should be chosen so they will not need to change in the future. +Best is to give the git server a DNS name of its own. + +Debian's dgit git server has special access control rules, +implemented in B<dgit-repos-server> and B<dgit-repos-policy-debian> +in the package B<dgit-infrastructure>. +but in most installations this is not needed. +If there is no or little distinction between +(i) developers who are entitled to upload (push) and +(ii) repository administrators, +then a it is sufficient to provide a +git server with a unix account for each user who will pushing, +perhaps using ssh restricted commands. + +=item Debian-format archive (repository) + +This holds the source packages. +You will probably use the same archive to host your binaries, +and point your B<apt> at it. + +dgit uses the term B<archive> for this. + +There are a variety of tools for +creating and managing a Debian-format archive. +In this document we will assume you are using B<reprepro>. + +Setting up reprepro is not covered in this tutorial. +Instead, we assume you already have reprepro working. + +You should also write appropriate dput configuration, +since dgit uses dput to upload packages to the archive. +This will involve choosing a dput host name. +That's probably your distro name, I<distro>. + +=back + +=head1 CONFIGURATION + +When you have all of the above set up, +you are ready to explain to dgit how to access your systems. + +dgit is configured via git's configuration system, +so this is done with git configuration. +See L<git-config(1)>. + +Below, each heading is one or more git config keys. +B<bold> is literal text and I<italics> +is things that vary. +In the descriptions of the effects of config settings, +we refer to the config values C<like this>. + +=over + +=item B<dgit-distro.>I<distro>B<.git-url>, B<.git-url-suffix> + +Specify the publicly accessible git URLs for your +dgit git server. The urls generated are +C<git-url>B</>I<package>C<git-url-suffix> + +The url should be stable, +and publicly accessible, +because its name is published in .dsc files. +(Note that if you make modified versions of packages from Debian, +the copyleft licences used for Free Software +often require you to permit your users, employees, and downstreams +to further distribute your modified source code.) + +=item B<dgit-distro.>I<distro>B</push.git-host> + +The domain name of your git server's ssh interface. + +=item B<dgit-distro.>I<distro>B</push.git-user-force> B<dgit-distro.>I<distro>B</push.username> + +Some git hosting systems expect everyone to +connect over ssh as the same user, often B<git>. +If this is the case, set C<git-user-force> to that user. + +If you have a normal git over ssh arrangement, +where people ssh as themselves, +leave C<git-user-force> unset. +If a user wishes to override the username +(for example, if their local username is not the same as on the server) +they can set C<username>. + +=item B<dgit-distro.>I<distro>B</push.git-url> + +Set this to the empty string. +This will arrange that push accesses to the ssh server will use +C</push.git-host>, etc. + +=item B<dgit-distro.>I<distro>B</push.git-proto> B<git+ssh://> + +=item C<dgit-distro.>I<distro>B</push.git-path> + +The path to your repositories. +dgit push will try to push to +C<git-proto>[C<git-user-force>|C<username>B<@>]C<git-path>B</>I<package>B<.git> + +=item B<dgit-distro.>I<distro>B<.git-check>, B<.git-check-suffix> + +dgit clone needs to be able to tell whether there is +yet a git repository for a particular package. + +If you always have a git repository for every package in your archive, +perhaps because you never use dput/dupload, and always dgit push, +Set C<git-check> to B<true>. + +Otherwise, set C<git-check> to a url prefix - ideally, https. +dgit clone will try to fetch +C<git-check>B</>I<package>C<git-check-suffix> +and expect to get either some successful fetch (it doesn't matter what) +or a file not found error (http 404 status code). +Other outcomes are fatal errors. + +If your git server runs cgit, +then you can set C<git-check> to the same as C<git-url>, +and C<git-check-suffix> to B</info/refs>. + +=item B<dgit-distro.>I<distro>B</push.git-check>, B</push.git-create> + +dgit push also needs to be able to check whether the repo exists. + +You can set both of these to B<ssh-cmd>, +which will use an ssh shell command to test repository existence. +Or leave them unset, and dgit push will use the readonly details. +If repositories are created automatically on push, somehow, +you can set C<git-create> to B<true>. + +=item B<dgit-distro.>I<distro>B<.upload-host> + +What I<host> value to pass to dput, to upload. + +This is a nickname, not the real host name. +You need to provide everyone who will push with an appropriate +dput configuration. +See L<dput.cf(5)>. + +A good nickname for your upload host is your distro name I<distro>. + +=item B<dgit-distro.>I<distro>B<.mirror> + +Set this to the url of your source package archive. +This is the same string as appears +in the 2nd field of each B<sources.list> entry. + +=item B<dgit-distro.>I<distro>B<.archive-query>, B<.archive-query-url> + +If you have a smallish distro, +set C<archive-query> to B<aptget:> (with a colon). + +If your distro is large +(eg, if it contains a substantial fraction of Debian) +then this will not be very efficient: +with this setting, +dgit often needs to download and update Sources files. + +For large distros, +it is better to implement the Debian archive ftpmaster API. +See L<https://api.ftp-master.debian.org/>, +and set C<archive-query> to B<ftpmasterapi:> (with a colon) +and C<archive-query-url> to your API base URL. +dgit uses these queries: +B<suites>, +B<dsc_in_suite/>I<isuite>B</>I<package> and +B<file_in_archive/>I<pat> +(so you need not implement anything else). + +Alternatively, +if your system supports the rmadison protocol, +you can set C<archive-query> to B<madison:>[I<madison-distro>]. +dgit will invoke B<rmadison> -uI<madison-distro>. + +=item B<dgit-suite.>I<suite>B<.distro> I<distro> + +Set this for every one of your suites. +You will have to update this when new suites are created. +If you forget, your users can explicitly specify B<-d> I<distro> +to dgit. + +=back + +=head1 TEMPLATE GIT REPOSITORY + +When dgit push is used for I<package> for the first time, +it must create a git repository on the git server. + +If C<git-create> is set to B<ssh-cmd>, +dgit will use the user's shell access to the server to +B<cp -a _template.git> I<package>B<.git>. +So you should create B<_template.git> with suitable contents. + +Note that the ssh rune invoked by dgit does not do any locking. +So if two people dgit push the same package at the same time, +there will be lossage. +Either don't do that, or set up B<dgit-repos-server>. + +=head1 SSH COMMANDS + +When a user who can push runs dgit, +dgit uses ssh to access the git server. + +To make ssh restricted command easier, +and for the benefit of dgit-repos-server, +dgit's ssh commands +each start with a parseable commentish rune. + +The ssh commands used by dgit are these: + +=over + +=item B<: dgit> I<distro> B<git-check> I<package> B<;>... + +Test whether I<package> has a git repo on the server already. +Should print B<0> or B<1> and a newline, +and exit status zero in either case. +The rest of the command, after B<;>, +is a shell implementation of this test. +Used when C<git-check> is set to B<ssh-cmd>. + +=item B<: dgit> I<distro> B<git-create> I<package> B<;>... + +Create the git repository for I<package> on the server. +See L</TEMPLATE GIT REPOSITORY>, above. +The rest of the command is an appropriate invocation of cd and cp. +Used when C<git-create> is set to B<ssh-cmd>. + +=item B<git-receive-pack>..., B<git-upload-pack>... + +dgit invokes git to access the repository; +git then runs these commands. +Note that dgit push will first do a git fetch over ssh, +so you must provide upload-pack as well as receive-pack. + +=back + +(There are also other ssh commands +which are historical or obscure.) + +=head1 SEE ALSO + +dgit(1) @@ -46,6 +46,7 @@ dgit-maint-debrebase(7) for maintainers: a pure-git rebasish workflow dgit-maint-merge(7) for maintainers: a pure-git merging workflow dgit-maint-gbp(7) for maintainers already using git-buildpackage dgit-sponsorship(7) for sponsors and sponsored contributors +dgit-downstream-dsc(7) setting up dgit push for a new distro .TE .LP See \fBdgit(7)\fP for detailed information about the data |