From 570a260553bdfac84e97ab996ab136ed1753573b Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Fri, 22 Jun 2018 19:37:57 +0100 Subject: [PATCH] WIP --- dgit-downstream-dsc.7.pod | 294 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 294 insertions(+) create mode 100644 dgit-downstream-dsc.7.pod diff --git a/dgit-downstream-dsc.7.pod b/dgit-downstream-dsc.7.pod new file mode 100644 index 00000000..49822194 --- /dev/null +++ b/dgit-downstream-dsc.7.pod @@ -0,0 +1,294 @@ +=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. +Your users will be able to get the source with B, +or with traditional tools such as B. + +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. + +=head1 NAMES + +You need to choose some names. + +=over + +=item "distro" name + +dgit understands each thing it interacts with as a B. +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 for your distro name. + +=item "suite" names + +In dgit and Debian archive terminology, a B 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 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 +BI +(note, not BI) on that server, +and to make tags +IBI and BIBI. + +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 and B, +needs to have at least read access to the git server. + +Debian's dgit git server has special access control rules, +implemented in B and B +in the package B. +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 at it. + +dgit uses the term B 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. + +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. + +=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 can be used. + +B 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 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 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 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 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 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 . -- 2.30.2