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.
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:
=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 *
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.
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 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
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.
+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.
=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
C<dgit -wgf [--quilt=...] push>
to do the upload.
-(If you switched to the quilt-cache dgit view,
+(It is possible to upload from
+the quilt-cache dgit view,
+but this will cause the debian/1.2.3-1 tag to be
+placed on this branch
+rather than the sponsee's working branch.
+Since this might be confusing,
+it is a good idea to switch back to the sponsee's view,
+after reviewing and before pushing.
+If you do want to upload from 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,
=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.
~ianmdlvl / dgit.git / blobdiff