From 8eba9566df60aa1f8f494b8947d2cf68a646c7d9 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Thu, 27 Oct 2016 14:00:45 +0100 Subject: [PATCH] dgit-sponsorship.7 (wip) Signed-off-by: Ian Jackson --- .gitignore | 1 + dgit-sponsorship.7.pod | 239 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 240 insertions(+) create mode 100644 dgit-sponsorship.7.pod diff --git a/.gitignore b/.gitignore index 1042f97f..d36f5c71 100644 --- a/.gitignore +++ b/.gitignore @@ -9,4 +9,5 @@ debian/debhelper-build-stamp dgit-user.7 dgit-nmu-simple.7 dgit-maint-merge.7 +dgit-sponsorship.7 substituted diff --git a/dgit-sponsorship.7.pod b/dgit-sponsorship.7.pod new file mode 100644 index 00000000..71fb2054 --- /dev/null +++ b/dgit-sponsorship.7.pod @@ -0,0 +1,239 @@ +=head1 NAME + +dgit-sponsorship - tutorial for Debian upload sponsorship, using git + +=head1 INTRODUCTION AND SCOPE + +This tutorial describes how a Debian sponsored contributor +and +their sponsoring DD (or DM) +can collaborate and publish using git. + +The sponsor must to be intending to use dgit for the upload. +(If the sponsor does not use dgit, +it is not possible to properly publish +a sponsee's git branch.) + +It is best if the sponsee also uses dgit; +but also covered (later on) is the case where +the sponsee provides a proposed upload in source package form, +but the sponsor would like to work in git. + +This tutorial does not provide a checklist for the sponsor's review. +Both contributors are expected to be familiar with Debian +packaging and Debian's processes, and with git. + +=head1 SPONSEE WORKFLOW + +This section is addressed to the sponsee: + +=head2 General + +You should prepare the package as if you were going +to upload it with C yourself. + +For a straightforward NMU, consult L. + +If you are the (prospective) maintainer, +you can adopt any suitable (dgit-compatible) +git workflow. +The L tutorials describe some of the possibilities. + +=head2 Upload preparation + +You should go through all of the steps +a self-uploading maintainer would do, +including building for ad hoc tests, +and checking via a formal build (eg using C) +that the package builds on sid (or the target release). + +At the point where you would, +if you were a DD, +do the actual upload +by running dgit push, +you hand off to your sponsor. + +If you were going to use one of the +C<--quilt=> +options to dgit, or +C or C, +you must specify that in your handoff email - see below. + +=head1 GIT+ORIGS BASED HANDOFF + +The elements of the handoff consists of: + +=over + +=item * + +The git branch. + +=item * + +Any .orig tarballs which will be needed. + +=item * + +Any dgit --quilt= (or --gbp or --dpm) option needed + +=item * + +Plus of course all the usual information about the state +of the package, +any caveats or areas you would like the sponsor to focus their review, +constraints about upload timing, etc. + +=back + +If the handoff is done by email, +the elements above should be a in a single, signed, message. + +=head2 git branch + +The sponsee should push their HEAD as a git branch +to any suitable git server. +They can use their own git server; +alioth is another possibility. + +The branch names used by the sponsee on their local machine, +and on the server, do not matter. + +The sponsee should not make a CI tag. + +Instead, the sponsor should include the +git commit id of their HEAD +in their handover email. + +=head2 orig tarballs + +If there are any .origs that are not in the archive already, +the sponsor will need them as part of the upload. + +The sponsee can put them on a suitable webserver, +or attach to an email. + +The sponsee should quote sha256sums of the .origs in their +handoff email. + +=head2 quilt options + +Some workflows involve git branches which are not natively +dgit-compatible. +Normally dgit will convert them as needed, during push. +You need to tell your sponsor if they need to use +C<--gbp> (aka C<--quilt=gbp>), +C<--dpm> (aka C<--quilt=dpm>), +or one of the other C<--quilt=> options. + + +=head1 SPONSOR WORKFLOW + +This part is addressed to the sponsor: + +=head2 Receiving and validating the sponsorship request + +You should check the signature on the email. + +Use C to fetch the git branch +prepared by your sponsee, +and obtain any .origs mentioned by the sponsee. + +Check the git commit ID of the sponsee's branch tip, +and the sha256sums of the .origs, +against the handoff email. + +Now you can check out the branch tip, +and do your substantive review. + +=head2 Dealing with branches that want --quilt= + +If your sponsee mentioned a C<--quilt> +option, and you don't want to grapple with their preferred tree format, +you can convert their tree into the standard dgit view: + +=over 4 + + % dgit -wgf quilt-fixup + [ Watch for a message about split brain, and if so: ] + % git checkout -b dgit-view-for-review refs/dgit-intern/quilt-cache + +=back + +You should check that what you're looking at is a descendant of +the sponsee's branch. + +=head2 Some hints which may help the review + +C will get you an up-to-date +C +showing what's in the archive already. + +C +will check that dgit can build an appropriate source package. + +There is no need to run debdiff. +dgit will not upload anything that doesn't unpack +to exactly the git commit you are pushing, +so you can rely on what you see in C. + +=head2 Doing the upload + +When you have completed your source review, +and use +C +or similar, to to the build, and then +C +to do the upload. + +(If you switched to the quilt-cache dgit view, +B pass the --quilt or --gbp or --dpm option again.) + +If this was the first upload done with dgit, +you may need to pass +C<--overwrite> +to dgit. + + +=head1 SPONSORING A NON-GIT-USING SPONSEE + +This part is addressed to the sponsor: + +If your sponsee does not use git, +you can still do your review with git, +and use dgit for the upload. + +Your sponsee will provide you with a source package: +that is, a .dsc and the files it refers to. +Obtain these files, and check signatures as appropriate. +Then: + +=over 4 + + % dgit clone PACKAGE + % cd PACKAGE + % dgit import-dsc /path/to/sponsee's.dsc +sponsee + % git checkout sponsee + +=back + +This will leave you looking at the sponsee's package, +formatted as a dgit branch. + +When you have finished your review and your tests, +you can do the +dgit sbuild and +dgit push directly from the "sponsee" branch. + +You will need to pass +C<--overwrite> +to dgit push for every successive upload. +This disables a safety catch which would normally spot +situations where changes are accidentally lost. +When your sponsee is sending you source packages - +perhaps multiple source pacakges with the same version number - +these safety catches are inevitably ineffective. + +=head1 SEE ALSO + +dgit(1), dgit(7), dgit-nmu-simple(7), dgit-maint-*(7) -- 2.30.2