--- /dev/null
+=head1 NAME
+
+dgit-downstream-dsc - tutorial for downstreams publishing source packages
+
+=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.
+Source packages are 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 dgit and git branches.
+You can push your source code as a git branch to an ordinary git server.
+See L<dgit-user(7)>.
+
+=head1 NAMES
+
+You need to choose some names.
+
+=over
+
+=item "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.
+
+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.
+
+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.
+
+=item "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
+sid> aka unstable>, buster aka testing,
+stretch aka stable.
+There are also ancillary suites like 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 is 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<you>B</>I<version> and B<archive/>I<you>B</>I<version>.
+
+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.
+
+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 git server with ordinary access control will do.
+
+=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<you>.
+
+=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.
+
+
+git config dgit-distro.raspbian.git-url https://dgit.raspbian.org/
+git config dgit-distro.raspbian.git-url-suffix .git
+git config dgit-distro.raspbian/push.git-url ""
+git config dgit-distro.raspbian/push.git-host dgit.raspbian.org
+git config dgit-distro.raspbian/push.git-user-force dgit
+git config dgit-distro.raspbian/push.git-proto "git+ssh://"
+git config dgit-distro.raspbian/push.git-path "/dgit/raspbian/repos"
+git config dgit-distro.raspbian.git-check "true"
+git config dgit-distro.raspbian.git-check-suffix "/info/refs"
+git config dgit-distro.raspbian/push.git-check "ssh-cmd"
+git config dgit-distro.raspbian/push.git-create "true"
+git config dgit-distro.raspbian.upload-host raspbian
+git config dgit-distro.raspbian.mirror http://archive.raspbian.org/raspbian
+git config dgit-distro.raspbian.archive-query "aptget:"
+git config dgit-suite.wheezy-staging.distro raspbian
+git config dgit-suite.jessie-staging.distro raspbian
+git config dgit-suite.stretch-staging.distro raspbian
+
+Please see the reprepro document for that.
+We
+
+
+If you do not want or need to
+
+set up
+arrangements so that
+
+ B<dgit push> can be used.
+
+B<dgit> can be incorporated into a
+git-buildpackage(1) package-maintenance workflow. This should be read
+jointly with git-buildpackage(1)'s documentation. Some reasons why
+you might want to incorporate B<dgit> into your existing workflow:
+
+=over 4
+
+=item
+
+Benefit from dgit's safety catches. In particular, ensure that your
+upload always matches exactly your git HEAD.
+
+=item
+
+Provide a better, more detailed git history to downstream dgit users,
+such as people using dgit to do an NMU (see dgit-nmu-simple(7) and
+dgit-user(7)).
+
+=back
+
+Note that we assume a patches-unapplied repository: the upstream
+source committed to the git repository is unpatched.
+git-buildpackage(1) can work with patched-applied repositories, but is
+normally used with patches-unapplied.
+
+=head1 GIT CONFIGURATION
+
+If you run
+
+=over 4
+
+ % git config dgit.default.quilt-mode gbp
+
+=back
+
+in your repository, you can omit I<--gbp> wherever it occurs below.
+
+Note that this does require that you always work from your gbp master
+branch, never the dgit patches-applied branch.
+
+=head1 BUILDING
+
+You can perform builds like this:
+
+=over 4
+
+ % dgit [--allow-dirty] gbp-build [OPTIONS]
+
+=back
+
+where I<--allow-dirty> is needed for testing uncommitted changes, and
+I<OPTIONS> are any further options to be passed on to
+gbp-buildpackage(1).
+
+When you are ready to build for upload, you will probably want to use
+sbuild(1) or pbuilder(1), or do a source-only upload. Either
+
+=over 4
+
+ % dgit --rm-old-changes --gbp sbuild
+
+=back
+
+or
+
+=over 4
+
+ % dgit --rm-old-changes gbp-build --git-pbuilder
+
+=back
+
+or
+
+=over 4
+
+ % dgit --rm-old-changes --gbp build-source
+
+=back
+
+We use I<--rm-old-changes> to ensure that there is exactly one changes
+file corresponding to this package, so we can be confident we're
+uploading what we intend (though B<dgit push> will do some safety
+checks).
+
+Note that all of the commands in this section are not required to
+upload with dgit. You can invoke gbp-buildpackage(1), pbuilder(1) and
+sbuild(1) directly. However, the defaults for these tools may leave
+you with something that dgit will refuse to upload because it doesn't
+match your git HEAD. As a general rule, leave all signing and tagging
+to dgit.
+
+=head1 UPLOADING
+
+Don't use I<--git-tag>: B<dgit push> will do this for you. To upload:
+
+=over 4
+
+ % dgit --gbp push
+
+=back
+
+This will push your git history to the dgit-repos, but you probably
+want to follow it up with a push to alioth.
+
+You will need to pass I<--overwrite> if the previous upload was not
+performed with dgit.
+
+If this is first ever dgit push of the package, consider passing
+I<--deliberately-not-fast-forward> instead of I<--overwrite>. This
+avoids introducing a new origin commit into the dgit view of your git
+history. (This origin commit would represent the most recent non-dgit
+upload of the package, but this should already be represented in your
+git history.)
+
+=head1 INCORPORATING NMUS
+
+B<dgit pull> can't yet incorporate NMUs into patches-unapplied gbp
+branches. You can just apply the NMU diff the traditional way. The
+next upload will require I<--overwrite>.
+
+=head1 SEE ALSO
+
+dgit(1), dgit(7)
+
+=head1 AUTHOR
+
+This tutorial was written and is maintained by Sean Whitton <spwhitton@spwhitton.name>.
~ianmdlvl / dgit.git / commitdiff