summaryrefslogtreecommitdiff
path: root/dgit-sponsorship.7.pod
diff options
context:
space:
mode:
authorIan Jackson <ijackson@chiark.greenend.org.uk>2016-10-30 23:56:29 +0000
committerIan Jackson <ijackson@chiark.greenend.org.uk>2016-10-30 23:56:29 +0000
commitcb809d942c58dea5dfba6ad8b7e3298338ebb24e (patch)
treed4316c3289f8e8efdd746dfaf3a51ecd0544c5b5 /dgit-sponsorship.7.pod
parent14a6daa486a195f465c8049122d20675d6626f07 (diff)
parent6e7c6b8b8305f162cea9e3da85c24b3f21888a1a (diff)
Merge branch 'wip.tutorials' into wip
Diffstat (limited to 'dgit-sponsorship.7.pod')
-rw-r--r--dgit-sponsorship.7.pod297
1 files changed, 297 insertions, 0 deletions
diff --git a/dgit-sponsorship.7.pod b/dgit-sponsorship.7.pod
new file mode 100644
index 0000000..8feb0d1
--- /dev/null
+++ b/dgit-sponsorship.7.pod
@@ -0,0 +1,297 @@
+=head1 NAME
+
+dgit-sponsorship - tutorial for Debian upload sponsorship, using git
+
+=head1 INTRODUCTION AND SCOPE
+
+This tutorial describes how a Debian sponsored contributor
+and
+a 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<dgit push> yourself.
+
+For a straightforward NMU, consult L<dgit-nmu-simple(7)>.
+
+If you are the (prospective) maintainer,
+you can adopt any suitable (dgit-compatible)
+git workflow.
+The L<dgit-maint-*(7)> 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<dgit sbuild>)
+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<dgit --gbp> or C<dgit --dpm>,
+you must specify that in your handoff email - see below.
+
+=head2 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 *
+
+A sample dgit push command, containing
+any dgit --quilt=, --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.
+This could be an RFS submission
+against the sponsorship-requests pseudo-package.
+
+=head3 git branch
+
+=over 4
+
+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 C<debian/>I<version> tag.
+
+Instead, the sponsee should include the
+git commit id of their HEAD
+in their handover email.
+
+=back
+
+=head3 orig tarballs
+
+=over 4
+
+If there are any .origs that are not in the archive already,
+the sponsor will need them as part of the upload.
+
+The simplest approach is to
+commit them with pristine-tar(1), e.g.
+
+=over 4
+
+ % pristine-tar commit ../foo_1.2.3.orig.tar.xz upstream/1.2.3
+
+=back
+
+and be sure to push the pristine-tar branch.
+If you are using git-buildpackage(1), just pass
+I<--git-pristine-tar> and I<--git-pristine-tar-commit>.
+
+Alternatively,
+the sponsee can put them on a suitable webserver,
+or attach to the e-mail,
+if they are small.
+
+The sponsee should quote sha256sums of the .origs in their
+handoff email.
+
+=back
+
+=head3 quilt options
+
+=over 4
+
+Some workflows involve git branches which are not natively
+dgit-compatible.
+Normally dgit will convert them as needed, during push.
+
+Supply a sample "dgit push" command
+including any
+C<--gbp> (aka C<--quilt=gbp>),
+C<--dpm> (aka C<--quilt=dpm>),
+or other C<--quilt=> option
+they need to use.
+e.g.
+
+=over 4
+
+ % dgit --gbp push
+
+=back
+
+=back
+
+=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<git fetch> or C<git clone> to obtain the git branch
+prepared by your sponsee,
+and obtain any .origs mentioned by the sponsee
+(to extract .origs committed with pristine-tar,
+you can use origtargz(1),
+or use "gbp clone --pristine-tar".)
+
+Check the git commit ID of the sponsee's branch tip,
+and the sha256sums of the .origs,
+against the handoff email.
+
+Confirm that the sponsee has not made
+a debian/1.2.3-1 tag.
+If they have,
+it is best to ask them to delete it now,
+as it can cause confusion later when dgit push produces its own tag.
+
+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=foo --dgit-view-save=unquilted quilt-fixup
+ % git checkout unquilted
+
+=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<dgit fetch sid> will get you an up-to-date
+C<refs/remotes/dgit/dgit/sid>
+showing what's in the archive already.
+
+C<dgit -wgf --damp-run push>
+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<git diff>.
+
+=head2 Doing the upload
+
+When you have completed your source review,
+and use
+C<dgit -wgf [--quilt=...] sbuild -A -C>
+or similar, to to the build, and then
+C<dgit -wgf [--quilt=...] push>
+to do the upload.
+
+(If you switched to the quilt-cache dgit view,
+B<do not> 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
+
+Or for an entirely new package:
+
+=over 4
+
+ % mkdir PACKAGE
+ % cd PACKAGE
+ % git init
+ % dgit -pPACKAGE import-dsc /path/to/sponsee's.dsc +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)