X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit-sponsorship.7.pod;h=3fbdac8651f7e15db0499740d3db1aad0aadeeed;hp=71fb2054286d2ad832dbfaff985e5f6c851f37a2;hb=2da706781c3db5e34375a6c3c0b8f72135b70c55;hpb=8eba9566df60aa1f8f494b8947d2cf68a646c7d9 diff --git a/dgit-sponsorship.7.pod b/dgit-sponsorship.7.pod index 71fb2054..3fbdac86 100644 --- a/dgit-sponsorship.7.pod +++ b/dgit-sponsorship.7.pod @@ -6,7 +6,7 @@ dgit-sponsorship - tutorial for Debian upload sponsorship, using git This tutorial describes how a Debian sponsored contributor and -their sponsoring DD (or DM) +a sponsoring DD (or DM) can collaborate and publish using git. The sponsor must to be intending to use dgit for the upload. @@ -30,7 +30,7 @@ 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. +to upload it with C or C yourself. For a straightforward NMU, consult L. @@ -59,7 +59,7 @@ options to dgit, or C or C, you must specify that in your handoff email - see below. -=head1 GIT+ORIGS BASED HANDOFF +=head2 git+origs based handoff The elements of the handoff consists of: @@ -71,11 +71,15 @@ The git branch. =item * -Any .orig tarballs which will be needed. +Any .orig tarballs which will be needed, +or sample git-archive(1) +or gbp-buildpackage(1) +command(s) to generate them. =item * -Any dgit --quilt= (or --gbp or --dpm) option needed +A sample dgit push command, containing +any dgit --quilt=, --gbp or --dpm option needed =item * @@ -88,44 +92,89 @@ constraints about upload timing, etc. 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. -=head2 git branch +=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. +salsa 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 +Instead, the sponsee should include the git commit id of their HEAD in their handover email. -=head2 orig tarballs +=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 sponsee can put them on a suitable webserver, -or attach to an email. +If the sponsee generated these tarballs with git-archive(1) +or gbp-buildpackage(1), +they can simply include a sample invocation of git-archive(1) +or ensure that a suitable gbp.conf is present +in the source package +to generate the tarball. + +Otherwise, the simplest approach is to +commit the orig tarballs +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. +handoff email, +unless they supplied commands to generate them. + +=back -=head2 quilt options +=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. -You need to tell your sponsor if they need to use + +Supply a sample "dgit push" command +including any C<--gbp> (aka C<--quilt=gbp>), C<--dpm> (aka C<--quilt=dpm>), -or one of the other C<--quilt=> options. +or other C<--quilt=> option +they need to use. +e.g. + +=over 4 + + % dgit --gbp push + +=back +=back =head1 SPONSOR WORKFLOW @@ -135,9 +184,12 @@ This part is addressed to the sponsor: You should check the signature on the email. -Use C to fetch the git branch +Use C or C to obtain the git branch prepared by your sponsee, -and obtain any .origs mentioned by the 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, @@ -154,9 +206,8 @@ 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 + % dgit -wgf --quilt=foo --dgit-view-save=unquilted quilt-fixup + % git checkout unquilted =back @@ -169,7 +220,7 @@ C will get you an up-to-date C showing what's in the archive already. -C +C will check that dgit can build an appropriate source package. There is no need to run debdiff. @@ -183,17 +234,39 @@ When you have completed your source review, and use C or similar, to to the build, and then +C +or C to do the upload. -(If you switched to the quilt-cache dgit view, -B pass the --quilt or --gbp or --dpm option again.) +Check whether the sponsee made a debian/I tag. +If they did, +ensure you have their tag in the repository you are pushing from, +or pass C<--no-dep14tag>. +This avoids identically named, non-identical tags, +which can be confusing. + +(It is possible to upload from +the quilt-cache dgit view. +If you want to do this, +B pass the C<--quilt> or C<--gbp> or C<--dpm> options again, +and B pass C<--no-dep14tag>, +since the debian/I tag +should go on the sponsee's branch.) If this was the first upload done with dgit, you may need to pass C<--overwrite> to dgit. +Alternatively, +if this was the first ever dgit push of the package, +you can pass C<--deliberately-not-fast-forward> +instead of C<--overwrite>. +This avoids introducing a new origin commit +into the dgit view of +the sponsee's git history +which is unnecessary and could be confusing. =head1 SPONSORING A NON-GIT-USING SPONSEE @@ -217,6 +290,17 @@ Then: =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.