=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.
See L<git-config(1)>.

=over

=item git url structure

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>I<package-name>C<git-url-suffix>.

Configure:

B<dgit-distro.>I<you>B<.git-url> = C<git-url>

B<dgit-distro.>I<you>B<.git-url-suffix> = C<git-url-suffix> (if any)

=item git server access via ssh

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>

Configure:

B<dgit-distro.>I<you>B</push.git-url> ""

B<dgit-distro.>I<you>B</push.git-host> C<push.git-host>

dgit-distro.I<you>/push.git-user-force C<push.git-user-force>
(eg you would set this too B<git> if your hosting service
expects every user to ssh to git@service)

C<dgit-distro.>I<you>B</push.git-proto> B<git+ssh://>

C<dgit-distro.>I<you>B</push.git-path> "/dgit/I<you>/repos"

=item git repository existence testing





=back

 for your git server,


its name for sshing into it,
and the path on the server 

Assuming your git server package



dgit-distro.I<you>.git-url-suffix .git


dgit-distro.I<you>.git-check "true"

dgit-distro.I<you>.git-check-suffix "/info/refs"

dgit-distro.I<you>/push.git-check "ssh-cmd"

dgit-distro.I<you>/push.git-create "true"

dgit-distro.I<you>.upload-host I<you>

dgit-distro.I<you>.mirror http://archive.I<you>.org/I<you>

dgit-distro.I<you>.archive-query "aptget:"

dgit-suite.wheezy-staging.distro I<you>

dgit-suite.jessie-staging.distro I<you>

dgit-suite.stretch-staging.distro I<you>



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>.