From 55f594f286fd74965a5973b69582e56413e3007c Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Sat, 30 Jun 2018 23:52:46 +0100 Subject: [PATCH] WIP --- dgit-downstream-dsc.5.pod | 47 --------- dgit-downstream-dsc.7.pod | 209 +++++++++----------------------------- 2 files changed, 46 insertions(+), 210 deletions(-) diff --git a/dgit-downstream-dsc.5.pod b/dgit-downstream-dsc.5.pod index eebfe999..cc741c0a 100644 --- a/dgit-downstream-dsc.5.pod +++ b/dgit-downstream-dsc.5.pod @@ -62,50 +62,3 @@ Set up your git server, as follows: 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-check "true" - 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 - - - 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. - diff --git a/dgit-downstream-dsc.7.pod b/dgit-downstream-dsc.7.pod index 3029ab47..f6aff7ec 100644 --- a/dgit-downstream-dsc.7.pod +++ b/dgit-downstream-dsc.7.pod @@ -150,7 +150,8 @@ dgit is configured via git's configuration system, so this is done with git configuration. See L. -Below, in the headings, B is literal text and I +Below, each heading is one or more git config keys. +B is literal text and I is things that vary. In the descriptions of the effects of config settings, we refer to the config values C. @@ -161,9 +162,15 @@ we refer to the config values C. Specify the publicly accessible git URLs for your dgit git server. The urls generated are -CIC +CBIC -The url should be stable because its name is published in .dsc files. +The url should be stable, +and publicly accessible, +because its name is published in .dsc files. +(Note that if you make modified versions of packages from Debian, +the copyleft licences used for Free Software +often require you to permit your users, employees, and downstreams +to further distribute your modified source code.) =item BIB @@ -216,183 +223,59 @@ If your git server runs cgit, then you can set C to the same as C, and C to B. -a package actually -has a git repository. +=item BIB, B -=item git repository existence testing +dgit push also needs to be able to check whether theh repo exists. -dgit needs to know how to check whether a particular package -has a git repository yet. +You can set both of these to B, +which will use an ssh shell command to test repository existence. +Or leave them unset, and dgit push will use the readonly details. +If repositories are created automatically0 on push, somehow, +you can set C to B. +=item BIB<.upload-host> +What I value to pass to dput, to upload. +This is a nickname, not the real host name. +You need to provide everyone who will push with an appropriate +dput configuration. +See L. +A good nickname for your upload host is your distro name I. -=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.git-check "true" - -dgit-distro.I.git-check-suffix "/info/refs" - -dgit-distro.I/push.git-check "ssh-cmd" - -dgit-distro.I/push.git-create "true" - -dgit-distro.I.upload-host I - -dgit-distro.I.mirror http://archive.I.org/I - -dgit-distro.I.archive-query "aptget:" - -dgit-suite.wheezy-staging.distro I - -dgit-suite.jessie-staging.distro I - -dgit-suite.stretch-staging.distro I +=item BIB<.mirror> +Set this to the url of your source package archive. +This is the same string as appears +in the 2nd field of each B entry. +=item BIB<.archive-query>, B<.archive-query-url> -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 +If you have a smallish distro, +set this to B (with acolon). -in your repository, you can omit I<--gbp> wherever it occurs below. +If your distro is large +(eg, if it contains a substantial fraction of Debian) +then this will not be very efficient: +with this setting, +dgit often needs to downloads and update Sources files. -Note that this does require that you always work from your gbp master -branch, never the dgit patches-applied branch. +For large distros, +it is better to implement the Debian archive ftpmaster API. +See L, +and set C to B (with a colon) +and C to your API base URL. -=head1 BUILDING +-item BIB<.distro> I -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 +Set this for every one of your suites. +You will have to update this when new suites are created. +If you forget, your users can explicitly specify B<-d> I 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 . +dgit(1) -- 2.30.2