WIP

diff --git a/dgit-downstream-dsc.5.pod b/dgit-downstream-dsc.5.pod
new file mode 100644 (file)
index 0000000..d8afcd4
--- /dev/null
+++ b/dgit-downstream-dsc.5.pod
@@ -0,0 +1,146 @@
+This guide is to help you if:
+
+ * you are a distro which is a downstream of Debian (directly
+   or indirectly)
+
+ * you want to publish source packages as well as git branches
+
+Not every option is covered here.  dgit(1) has a mostly-complete list
+of config options, although not always with useful descriptions.
+
+You will need to choose a DISTRO name for your distro.  This should be
+stable; globally unique; preferably not contain full stops or
+underscores; and preferably be lowercase.
+
+You will also need:
+
+ * Software to manage a Debian-format archive, suitable for use
+   by apt (including apt-get source).  I suggest reprepro.
+   This guide will not help you much with setting up reprepro.
+
+ * A git server.  It must accessible push by ssh, and by anonymous
+   internet users (by the git https smart protocol, preferably;
+   failing that, git:// or plain http might do, although they
+   leave your dgit users vulnerable).
+
+   There are various options for the git server, depending on how much
+   you trust your uploaders.  There are four levels of trust and
+   sophistication:
+
+ shell account
+
+   For use when uploaders have shell accounts on the server and you
+   trust them completely.  You then do not need to install any special
+   software on the server.
+
+ dgit-repos-server
+
+   Your uploaders do not (necessarily) have shell accounts.
+   You will need to collect their ssh keys and also their PGP
+   signing keys.  You can restrict uploads on a per-package
+   per-key basis by using the Debian `dm.txt' format.
+
+ dgit-repos-server + policy hook
+
+   You want to impose additional policy.  For example, Debian's
+   copyright review process means that uploads of new packages are
+   initially not public: dgit-repos-policy-debian is an example.
+
+ custom implementation
+
+   From the dgit client's point of view, the dgit git server is a git
+   server accessed by ssh (when pushing) or https (when fetching).
+   You may use anything that has the right properties for your needs.
+   dgit primarily authenticates pushes by signing tags, so your
+   software will probably need to check and verify that tag
+   appropriately before accepting a push.  dgit-repos-server knows how
+   to do this properly.
+
+Set up your git server, as follows:
+
+ shell account
+
+   Make a suitable (sub)directory.  You should create a _template.git
+   bare repo, with appropriate permissions.  When new packages are
+   uploaded, this _template.git will be copied.  You will probably
+   want to set core.sharedRepository in the template, and/or arrange
+   for personal groups and 002 umask.
+
+ dgit-repos-server
+
+   Additionally, install dgit-infrastructure.  Create a service
+   account `dgit' on the server.  For each authorised uploader, put
+   their ssh key in dgit's authorized_keys file, with a
+   restricted_command specifying the dgit-repos-server invocation.
+   Put the keyring where dgit-repos-server can find it.
+   Consult the comment at the top of dgit-repos-server for the
+   restricted command rune.
+
+You should set the following global (or user) git config options:
+
+  dgit-distro.DISTRO.git-url
+  dgit-distro.DISTRO.git-url-suffix
+    Specifies the publicly accessible git URLs for your
+    dgit git server.  The urls generated are
+      <git-url><PACKAGE><git-url-suffix>
+    The url should be stable.
+
+  dgit-distro.DISTRO/push.git-url    ""
+  dgit-distro.DISTRO/push.git-host
+    FQDN of your git server's ssh interface
+
+  dgit-distro.DISTRO/push.git-user-force
+    Set to `dgit' if you are not using `shell account' mode
+  dgit-distro.DISTRO/push.username
+    Each user's username on the server, when using `shell
+    account' mode.
+
+  dgit-distro.DISTRO/push.git-proto   "git+ssh://"
+  dgit-distro.DISTRO/push.git-path    "/dgit/DISTRO/repos"
+    (Or in shell account mode, whereever your repos are.)
+
+  dgit-distro.DISTRO.git-check        "true"
+  dgit-distro.DISTRO.git-check-suffix "/info/refs"
+    This works with cgit.  What's needed is a way to construct a URL
+    which will retrieve some object if the repo exists on the server,
+    or give 404 otherwise.  The urls are 
+      <git-check><PACKAGE><git-check-suffix>
+
+  dgit-distro.DISTRO/push.git-check   "ssh-cmd"
+
+  dgit-distro.DISTRO/push.git-create  "ssh-cmd"
+    For shell account mode
+  dgit-distro.DISTRO/push.git-create  "true"
+    For dgit-repos-server
+
+  dgit-distro.DISTRO.upload-host
+    What "host" value to pass to dput, to upload.
+
+dgit clients need to access your archive as well as the dgit git
+server.  This enables them to see which packages are actually "in your
+archive".
+
+When they download source packages, they use a mirror:
+  dgit-distro.DISTRO.mirror "https://ftp.example.com"
+(data from mirrors is verified using pgp, so plain http is OK;
+https is better for privacy.)
+
+You should ideally provide some kind of API to enable dgit clients to
+rapidly find information about a specific package.  For example, DAK
+(the Debian Archive Kit) as used by Debian provides the ftpmaster API at
+  https://api.ftp-master.debian.org/
+
+If you do this, then you can set:
+  dgit-distro.DISTRO.archive-query  "ftpmasterapi:"
+  dgit-distro.DISTRO.archive-query-url", "https://ftpapi.example.com/"
+
+dgit can fall back to using the Packages files, like apt does.
+This is often slower because clients must download information
+about the whole distro even though dgit only wants one package
+(at a time, anyway).  (There is some cacheing.)  To use this,
+specify
+  dgit-distro.DISTRO.archive-query "aptget:"
+and it will find the data from the specified mirror.  In this case you
+will need to make sure your local apt has the appropriate keys so
+that it can verify the release signatures from the mirror.
+