i18n: i18n-diff-auditor: add usage message

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

diff --git a/dgit-sponsorship.7.pod b/dgit-sponsorship.7.pod
index e6c773044e772b53567bbf68492fb384475c44d6..3fbdac8651f7e15db0499740d3db1aad0aadeeed 100644 (file)
--- 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
 
 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.
 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
 =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)>.
 
 
 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.
 
 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:
 
 
 The elements of the handoff consists of:
 


@@ -71,11 +71,15 @@ The git branch.
 
 =item *
 
 
 =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 *
 
 
 =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 *
 
 
 =item *
 


@@ -88,30 +92,44 @@ constraints about upload timing, etc.
 
 If the handoff is done by email,
 the elements above should be a in a single, signed, message.
 
 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;
 
 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 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.
 
 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.
 
 
 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
 
 
 =over 4
 


@@ -129,18 +147,34 @@ or attach to the e-mail,
 if they are small.
 
 The sponsee should quote sha256sums of the .origs in their
 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.
 
 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>),
 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
 
 
 =head1 SPONSOR WORKFLOW
 


@@ -150,11 +184,12 @@ This part is addressed to the sponsor:
 
 You should check the signature on the email.
 
 
 You should check the signature on the email.
 

-Use C<git fetch> to fetch the git branch
+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,
 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,
 
 Check the git commit ID of the sponsee's branch tip,
 and the sha256sums of the .origs,


@@ -171,9 +206,8 @@ you can convert their tree into the standard dgit view:
 
 =over 4
 
 
 =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
 
 
 =back
 


@@ -186,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<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.
 will check that dgit can build an appropriate source package.
 
 There is no need to run debdiff.


@@ -200,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
 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.
 
 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.
 
 
 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
 
 
 =head1 SPONSORING A NON-GIT-USING SPONSEE
 


@@ -234,6 +290,17 @@ Then:
 
 =back
 
 
 =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.
 
 This will leave you looking at the sponsee's package,
 formatted as a dgit branch.