From 8eba9566df60aa1f8f494b8947d2cf68a646c7d9 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Thu, 27 Oct 2016 14:00:45 +0100 Subject: dgit-sponsorship.7 (wip) Signed-off-by: Ian Jackson --- dgit-sponsorship.7.pod | 239 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 239 insertions(+) create mode 100644 dgit-sponsorship.7.pod (limited to 'dgit-sponsorship.7.pod') diff --git a/dgit-sponsorship.7.pod b/dgit-sponsorship.7.pod new file mode 100644 index 0000000..71fb205 --- /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) -- cgit v1.2.3 From a6c7e5fd1684f8a7621cdf168c285319fa5c84db Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Sat, 29 Oct 2016 07:26:24 -0700 Subject: dgit-sponsorship(7): Suggest pristine-tar(1) Signed-off-by: Sean Whitton --- dgit-sponsorship.7.pod | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) (limited to 'dgit-sponsorship.7.pod') diff --git a/dgit-sponsorship.7.pod b/dgit-sponsorship.7.pod index 71fb205..e6c7730 100644 --- a/dgit-sponsorship.7.pod +++ b/dgit-sponsorship.7.pod @@ -110,8 +110,23 @@ in their handover email. 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 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. @@ -137,7 +152,9 @@ 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. +and obtain any .origs mentioned by the sponsee +(to extract .origs committed with pristine-tar, +you can use origtargz(1).) Check the git commit ID of the sponsee's branch tip, and the sha256sums of the .origs, -- cgit v1.2.3 From 1e4e44e19d1e2b24c1d7b4cbb0057662ee8434ee Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Sat, 29 Oct 2016 07:28:43 -0700 Subject: dgit-sponsorship(7): "sample dgit push" Signed-off-by: Sean Whitton --- dgit-sponsorship.7.pod | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) (limited to 'dgit-sponsorship.7.pod') diff --git a/dgit-sponsorship.7.pod b/dgit-sponsorship.7.pod index e6c7730..40410e1 100644 --- a/dgit-sponsorship.7.pod +++ b/dgit-sponsorship.7.pod @@ -75,7 +75,8 @@ Any .orig tarballs which will be needed. =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 * @@ -136,11 +137,22 @@ handoff email. 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 -- cgit v1.2.3 From c316aea690adbd7c1701043b7addac4a8adbf36d Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Sat, 29 Oct 2016 07:29:08 -0700 Subject: dgit-sponsorship(7): Mention RFS procedure Signed-off-by: Sean Whitton --- dgit-sponsorship.7.pod | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'dgit-sponsorship.7.pod') diff --git a/dgit-sponsorship.7.pod b/dgit-sponsorship.7.pod index 40410e1..45889fc 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. @@ -89,6 +89,8 @@ 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 @@ -162,7 +164,7 @@ 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 (to extract .origs committed with pristine-tar, -- cgit v1.2.3 From 7b057ccd4fca9ada5be78a3a92513f7734d51aff Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Sat, 29 Oct 2016 07:29:30 -0700 Subject: dgit-sponsorship(7): Correct sponsee/sponsor Signed-off-by: Sean Whitton --- dgit-sponsorship.7.pod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'dgit-sponsorship.7.pod') diff --git a/dgit-sponsorship.7.pod b/dgit-sponsorship.7.pod index 45889fc..67d0647 100644 --- a/dgit-sponsorship.7.pod +++ b/dgit-sponsorship.7.pod @@ -104,7 +104,7 @@ 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. -- cgit v1.2.3 From 5439ecadb25350a6a5a63097fcaeabaf656128e6 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Sat, 29 Oct 2016 07:29:44 -0700 Subject: dgit-sponsorship(7): Demote to subsection Signed-off-by: Sean Whitton --- dgit-sponsorship.7.pod | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) (limited to 'dgit-sponsorship.7.pod') diff --git a/dgit-sponsorship.7.pod b/dgit-sponsorship.7.pod index 67d0647..3b8c3a8 100644 --- a/dgit-sponsorship.7.pod +++ b/dgit-sponsorship.7.pod @@ -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: @@ -92,7 +92,9 @@ 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. @@ -108,7 +110,11 @@ 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. @@ -134,7 +140,11 @@ if they are small. The sponsee should quote sha256sums of the .origs in their handoff email. -=head2 quilt options +=back + +=head3 quilt options + +=over 4 Some workflows involve git branches which are not natively dgit-compatible. -- cgit v1.2.3 From f4ce340d73232e6e5643ea2e88a1e36daed967cb Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Sat, 29 Oct 2016 08:53:35 -0700 Subject: dgit-sponsorship(7): Mention gbp-clone Signed-off-by: Sean Whitton --- dgit-sponsorship.7.pod | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'dgit-sponsorship.7.pod') diff --git a/dgit-sponsorship.7.pod b/dgit-sponsorship.7.pod index 3b8c3a8..9fe8abc 100644 --- a/dgit-sponsorship.7.pod +++ b/dgit-sponsorship.7.pod @@ -178,7 +178,8 @@ Use C or C 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).) +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, -- cgit v1.2.3 From 1468397432c47b2a779570991f228c81622bce81 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Sat, 29 Oct 2016 10:58:11 -0700 Subject: dgit-sponsorship(7): Add import-dsc for NEW package Signed-off-by: Sean Whitton --- dgit-sponsorship.7.pod | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'dgit-sponsorship.7.pod') diff --git a/dgit-sponsorship.7.pod b/dgit-sponsorship.7.pod index 9fe8abc..2bc9454 100644 --- a/dgit-sponsorship.7.pod +++ b/dgit-sponsorship.7.pod @@ -259,6 +259,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. -- cgit v1.2.3 From 55acc92c353623f0896469c29c65f3b951e270e7 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Sat, 29 Oct 2016 15:37:28 -0700 Subject: dgit-sponsorship(7): About deleting tag Signed-off-by: Sean Whitton --- dgit-sponsorship.7.pod | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'dgit-sponsorship.7.pod') diff --git a/dgit-sponsorship.7.pod b/dgit-sponsorship.7.pod index 2bc9454..a32585b 100644 --- a/dgit-sponsorship.7.pod +++ b/dgit-sponsorship.7.pod @@ -185,6 +185,12 @@ 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. -- cgit v1.2.3 From cd6e230475d630e1dc1e17e4142a27ad3eb3025d Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Sun, 30 Oct 2016 11:50:08 -0700 Subject: dgit-sponsorship(7): Suggest --dgit-view-save Signed-off-by: Sean Whitton --- dgit-sponsorship.7.pod | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'dgit-sponsorship.7.pod') diff --git a/dgit-sponsorship.7.pod b/dgit-sponsorship.7.pod index a32585b..8feb0d1 100644 --- a/dgit-sponsorship.7.pod +++ b/dgit-sponsorship.7.pod @@ -202,9 +202,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 -- cgit v1.2.3