From 177768519130da7d21705598f2b5d961cf408a4b Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Mon, 9 Jul 2018 00:44:09 +0100 Subject: [PATCH] dgit-downstream-dsc(7): New manpage. Closes:#842643,#851194. Signed-off-by: Ian Jackson --- .gitignore | 1 + Makefile | 1 + debian/changelog | 1 + dgit-downstream-dsc.7.pod | 354 ++++++++++++++++++++++++++++++++++++++ dgit.1 | 1 + 5 files changed, 358 insertions(+) create mode 100644 dgit-downstream-dsc.7.pod diff --git a/.gitignore b/.gitignore index ba7af789..a635e97c 100644 --- a/.gitignore +++ b/.gitignore @@ -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 diff --git a/Makefile b/Makefile index 605b5802..0ea7a7c9 100644 --- a/Makefile +++ b/Makefile @@ -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 6a992d22..6f72c5e4 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 00000000..fcbce058 --- /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. +Your users will be able to get the source with B, +or with traditional tools such as B. + +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. + +Not every option is covered here. +L 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 name + +dgit understands each thing it interacts with as a B. +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 for your distro name. + +=item I names + +In dgit and Debian archive terminology, a B is a line of +development, and/or a Debian release. +For example, at the time of writing, Debian has suites like +B aka B, B aka B, +and B aka B. +There are also ancillary suites like B. + +If your releases align with Debian's releases, +then your suites should contain the Debian suite names. +B 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 +BI +(note, not BI) on that server, +and to make tags +IBI and BIBI. +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 and B, +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 and B +in the package B. +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 at it. + +dgit uses the term B 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. + +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. + +=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. + +Below, each heading is one or more git config keys. +B is literal text and I +is things that vary. +In the descriptions of the effects of config settings, +we refer to the config values C. + +=over + +=item BIB<.git-url>, B<.git-url-suffix> + +Specify the publicly accessible git URLs for your +dgit git server. The urls generated are +CBIC + +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 BIB + +The domain name of your git server's ssh interface. + +=item BIB BIB + +Some git hosting systems expect everyone to +connect over ssh as the same user, often B. +If this is the case, set C to that user. + +If you have a normal git over ssh arrangement, +where people ssh as themselves, +leave C 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. + +=item BIB + +Set this to the empty string. +This will arrange that push accesses to the ssh server will use +C, etc. + +=item BIB B + +=item CIB + +The path to your repositories. +dgit push will try to push to +C[C|CB<@>]CBIB<.git> + +=item BIB<.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 to B. + +Otherwise, set C to a url prefix - ideally, https. +dgit clone will try to fetch +CBIC +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 to the same as C, +and C to B. + +=item BIB, B + +dgit push also needs to be able to check whether the repo exists. + +You can set both of these to B, +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 to B. + +=item BIB<.upload-host> + +What I 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. + +A good nickname for your upload host is your distro name I. + +=item BIB<.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 entry. + +=item BIB<.archive-query>, B<.archive-query-url> + +If you have a smallish distro, +set C to B (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, +and set C to B (with a colon) +and C to your API base URL. +dgit uses these queries: +B, +BIBI and +BI +(so you need not implement anything else). + +Alternatively, +if your system supports the rmadison protocol, +you can set C to B[I]. +dgit will invoke B -uI. + +=item BIB<.distro> I + +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 +to dgit. + +=back + +=head1 TEMPLATE GIT REPOSITORY + +When dgit push is used for I for the first time, +it must create a git repository on the git server. + +If C is set to B, +dgit will use the user's shell access to the server to +B IB<.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. + +=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 B I B<;>... + +Test whether I 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 is set to B. + +=item B<: dgit> I B I B<;>... + +Create the git repository for I on the server. +See L, above. +The rest of the command is an appropriate invocation of cd and cp. +Used when C is set to B. + +=item B..., B... + +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) diff --git a/dgit.1 b/dgit.1 index 67aa2fab..1460938a 100644 --- a/dgit.1 +++ b/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 -- 2.30.2