chiark / gitweb /
dgit-downstream-dsc(7): New manpage.
authorIan Jackson <ijackson@chiark.greenend.org.uk>
Sun, 8 Jul 2018 23:44:09 +0000 (00:44 +0100)
committerIan Jackson <ijackson@chiark.greenend.org.uk>
Sun, 8 Jul 2018 23:48:02 +0000 (00:48 +0100)
Closes:#842643,#851194.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
.gitignore
Makefile
debian/changelog
dgit-downstream-dsc.7.pod [new file with mode: 0644]
dgit.1

index ba7af78..a635e97 100644 (file)
@@ -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
index 605b580..0ea7a7c 100644 (file)
--- 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
index 6a992d2..6f72c5e 100644 (file)
@@ -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 (file)
index 0000000..fcbce05
--- /dev/null
@@ -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)
diff --git a/dgit.1 b/dgit.1
index 67aa2fa..1460938 100644 (file)
--- 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