test suite: gdr-unprocessable: new test

[dgit.git] / dgit-sponsorship.7.pod

diff --git a/dgit-sponsorship.7.pod b/dgit-sponsorship.7.pod
index 45889fcf2bb82db8fa35800204f9b5ea6d129615..3fbdac8651f7e15db0499740d3db1aad0aadeeed 100644 (file)
--- a/dgit-sponsorship.7.pod
+++ b/dgit-sponsorship.7.pod
@@ -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<dgit push> yourself.
+to upload it with C<dgit push-source> or C<dgit push> yourself.
 
 For a straightforward NMU, consult L<dgit-nmu-simple(7)>.
 
@@ -59,7 +59,7 @@ options to dgit, or
 C<dgit --gbp> or C<dgit --dpm>,
 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,7 +71,10 @@ 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 *
 
@@ -92,29 +95,41 @@ 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 C<debian/>I<version> 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 simplest approach is to
-commit them with pristine-tar(1), e.g.
+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
 
@@ -132,9 +147,14 @@ 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.
@@ -168,7 +188,8 @@ 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).)
+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,
@@ -185,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
 
@@ -200,7 +220,7 @@ 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>
+C<dgit -wgf --damp-run push-source>
 will check that dgit can build an appropriate source package.
 
 There is no need to run debdiff.
@@ -214,17 +234,39 @@ 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-source>
+or
 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.)
+Check whether the sponsee made a debian/I<version> 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<do not> pass the C<--quilt> or C<--gbp> or C<--dpm> options again,
+and B<do> pass C<--no-dep14tag>,
+since the debian/I<version> 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
 
@@ -248,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.