WIP

diff --git a/dgit-downstream-dsc.5.pod b/dgit-downstream-dsc.5.pod
index d8afcd4bb95c475ff5b0c0ecf2b1f0f00535737e..eebfe9998f8dbf1641b420d6c26ee43aba37aaf1 100644 (file)
--- a/dgit-downstream-dsc.5.pod
+++ b/dgit-downstream-dsc.5.pod
@@ -5,23 +5,9 @@ This guide is to help you if:
 
  * 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).
+ * A git server.  [...]
 
    There are various options for the git server, depending on how much
    you trust your uploaders.  There are four levels of trust and
@@ -78,29 +64,8 @@ Set up your git server, as follows:
 
 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"
+  dgit-distro.DISTRO.git-check-suffix ""
     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 

diff --git a/dgit-downstream-dsc.7.pod b/dgit-downstream-dsc.7.pod
index 062ad98409cdb3f976e96a13f59a097076b3f1c7..3029ab4705c33ba4e0bff1bc547dd48eb1456cb6 100644 (file)
--- a/dgit-downstream-dsc.7.pod
+++ b/dgit-downstream-dsc.7.pod
@@ -22,6 +22,10 @@ you can work as a Debian downstream purely using dgit and git branches.
 You can push your 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.
@@ -36,18 +40,22 @@ 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 alphanumerics and B<. + ->,
-although B<-> may be confusing and probably best avoided.
+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<you> for your distro name.
+I<distro> for your distro name.
 
 =item "suite" names
 
@@ -86,7 +94,8 @@ 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<you>B</>I<version> and B<archive/>I<you>B</>I<version>.
+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,
@@ -95,6 +104,11 @@ 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 should have a stable name and path structure.
+Best is to give it 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>
@@ -123,7 +137,7 @@ 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<you>.
+That's probably your distro name, I<distro>.
 
 =back
 
@@ -136,46 +150,74 @@ dgit is configured via git's configuration system,
 so this is done with git configuration.
 See L<git-config(1)>.
 
+Below, in the headings, 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 git url structure
+=item B<dgit-distro.>I<distro>B<.git-url>, B<.git-url-suffix>
 
-The format of the readonly unauthenticated urls
-(hopefully https, but http or git will do)
-for your packages' git repos.
-These will be of the form:
-C<git-url>B</>I<package-name>C<git-url-suffix>.
+Specify the publicly accessible git URLs for your
+dgit git server.  The urls generated are
+C<git-url>I<package>C<git-url-suffix>
 
-Configure:
+The url should be stable because its name is published in .dsc files.
 
-B<dgit-distro.>I<you>B<.git-url> = C<git-url>
+=item B<dgit-distro.>I<distro>B</push.git-host>
 
-B<dgit-distro.>I<you>B<.git-url-suffix> = C<git-url-suffix> (if any)
+The domain name of your git server's ssh interface.
 
-=item git server access via ssh
+=item B<dgit-distro.>I<distro>B</push.git-user-force> B<dgit-distro.>I<distro>B</push.username>
 
-dgit push will either
-B<ssh> I<localusername>B<@>C<push.git-host>
-or
-B<ssh> C<push.git-user-force>B<@>C<push.git-host>
-and expect to find the repos in
-C<push.git-path>B/>I<package-name>C<push.git-url-suffix>
+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>
 
-Configure:
+Set this to the empty string.
+This will arrange that push accesses to the ssh server will use
+C</push.git-host>, etc.
 
-B<dgit-distro.>I<you>B</push.git-url> ""
+=item B<dgit-distro.>I<distro>B</push.git-proto> B<git+ssh://>
 
-B<dgit-distro.>I<you>B</push.git-host> C<push.git-host>
+=item C<dgit-distro.>I<distro>B</push.git-path>
 
-dgit-distro.I<you>/push.git-user-force C<push.git-user-force>
-(eg you would set this to B<git> if your hosting service
-expects every user to ssh to git@service)
+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>
 
-C<dgit-distro.>I<you>B</push.git-proto> B<git+ssh://>
+=item B<dgit-distro.>I<distro>B<.git-check>, B<.git-check-suffix>
 
-C<dgit-distro.>I<you>B</push.git-path> C<push.git-path> (eg B</srv/dgit/>I<you>B</repos>)
+dgit clone needs to be able to tell whether there is
+yet a git repository for a particular package.
 
-C<dgit-distro.>I<you>B</push.git-url-suffix> C<push.git-url-suffix> (if any)
+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>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>.
+
+a package actually
+has a git repository.
 
 =item git repository existence testing
 
@@ -198,28 +240,25 @@ Assuming your git server package
 
 
 
-dgit-distro.I<you>.git-url-suffix .git
-
-
-dgit-distro.I<you>.git-check "true"
+dgit-distro.I<distro>.git-check "true"
 
-dgit-distro.I<you>.git-check-suffix "/info/refs"
+dgit-distro.I<distro>.git-check-suffix "/info/refs"
 
-dgit-distro.I<you>/push.git-check "ssh-cmd"
+dgit-distro.I<distro>/push.git-check "ssh-cmd"
 
-dgit-distro.I<you>/push.git-create "true"
+dgit-distro.I<distro>/push.git-create "true"
 
-dgit-distro.I<you>.upload-host I<you>
+dgit-distro.I<distro>.upload-host I<distro>
 
-dgit-distro.I<you>.mirror http://archive.I<you>.org/I<you>
+dgit-distro.I<distro>.mirror http://archive.I<distro>.org/I<distro>
 
-dgit-distro.I<you>.archive-query "aptget:"
+dgit-distro.I<distro>.archive-query "aptget:"
 
-dgit-suite.wheezy-staging.distro I<you>
+dgit-suite.wheezy-staging.distro I<distro>
 
-dgit-suite.jessie-staging.distro I<you>
+dgit-suite.jessie-staging.distro I<distro>
 
-dgit-suite.stretch-staging.distro I<you>
+dgit-suite.stretch-staging.distro I<distro>