non-native Debian package using B<dgit>. We maintain the Debian delta
as a series of git commits on our master branch. We use
git-debrebase(1) to shuffle our branch such that this series of git
-commits appears at the end of the branch. This does not involve
-rewriting any public git history.
+commits appears at the end of the branch. All the public git history
+is fast-forwarding, i.e., we do not rewrite and force-push.
Some advantages of this workflow:
=item
-Manipulate the patch queue using the full power of git-rebase(1),
-instead of relying on quilt(1), and without having to switch away to
-another branch, as with gbp-pq(1).
+Manipulate the delta queue using the full power of git-rebase(1),
+instead of relying on quilt(1), and without having to switch back and
+forth between patches-applied and patches-unapplied branches when
+committing changes and trying to build, as with gbp-pq(1).
+
+=item
+
+If you are using 3.0 (quilt), provide your delta queue as a properly
+separated series of quilt patches in the source package that you
+upload to the archive (unlike with dgit-maint-merge(7)).
=item
where it can benefit downstream dgit users, such as people using dgit
to do an NMU (see dgit-nmu-simple(7) and dgit-user(7)).
+=item
+
+Minimise the amount you need to know about 3.0 (quilt) in order to
+maintain Debian source packages which use that format.
+
=back
This workflow is appropriate for packages where the Debian delta
contains multiple pieces which interact, or which you don't expect to
be able to upstream soon. For packages with simple and/or short-lived
Debian deltas, use of git-debrebase(1) might introduce unneeded
-complexity. For such packages, consider the workflow described in
-dgit-maint-merge(7).
+complexity (for examples, see "BEHAVIOUR TO AVOID" below). For such
+packages, consider the workflow described in dgit-maint-merge(7).
=head1 INITIAL DEBIANISATION
-=head2 When upstream tags releases in git
-
This section explains how to start using this workflow with a new
package. It should be skipped when converting an existing package to
this workflow.
+=head2 When upstream tags releases in git
+
Suppose that the latest stable upstream release is 1.2.2, and this has
been tagged '1.2.2' by upstream.
Now go ahead and Debianise your package. Just make commits on the
master branch, adding things in the I<debian/> directory. If you need
-to patch the upstream source, see "EDITING THE PATCH QUEUE", below.
+to patch the upstream source, see "EDITING THE DELTA QUEUE", below.
Note that there is no need to maintain a separate 'upstream' branch,
unless you also happen to be involved in upstream development. We
-work with upstream tags rather than any branches, except when
-forwarding patches (see FORWARDING PATCHES UPSTREAM, below).
+work with upstream tags rather than any branches, except temporary
+branches used to prepare patches for forwarding upstream, for example.
Finally, you need an orig tarball:
=back
If your tree is patches-unapplied, you will need to make a commit
-corresponding to each of the quilt patches. gbp-pq(1) can do this for
-us:
+corresponding to each of the quilt patches. You can use
+
+=over 4
+
+ git debrebase convert-from-gbp
+
+=back
+
+or manually with gbp-pq(1):
=over 4
=back
-=head1 EDITING THE PATCH QUEUE
+=head1 EDITING THE DELTA QUEUE
=head2 Adding new patches
=back
-For example,
-
-=over 4
-
- % git debrebase -- --autosquash
-
-=back
-
A third alternative is to have git-debrebase(1) shuffle all the Debian
changes to the end of your branch, and then manipulate them yourself
using git-rebase(1). For example,
=over 4
% git debrebase launder
- % git rebase -i HEAD^5 # there are 4 Debian patches
+ % git rebase -i HEAD~5 # there are 4 Debian patches
=back
+If you take this approach, you should be very careful not to start the
+rebase earlier than the beginning of the delta queue.
+
=head2 Editing patches: finishing a debrebase
After completing the git rebase, your branch will not be a
=over 4
+ % git debrebase launder
% git debrebase stitch
=back
Note that each time you stitch a debrebase you introduce a pseudomerge
into your git history, which may make it harder to read. Try to do
-all of the editing of the patch queue that you think will be needed
+all of the editing of the delta queue that you think will be needed
for this upload in a single debrebase, so that there is a single
debrebase stitch.
A strategy is to debrebase only right before you upload. Before that
-point, instead of editing the existing patch series, you append fixup
+point, instead of editing the existing delta queue, you append fixup
commits (and reversions of commits) that alter the upstream source to
the required state. You can freely push and pull from
B<salsa.debian.org> during this. Just before uploading, you debrebase
the package build (for example, you don't want to commit your changes
to git), you can just run dpkg-buildpackage(1) or debuild(1) instead.
-=head2 Laundering the patch queue before uploading
+=head2 Laundering the delta queue before uploading
Just before you B<dgit push> or B<dgit push-source>, you might want to
-have git-debrebase(1) shuffle your branch such that the Debian patch
+have git-debrebase(1) shuffle your branch such that the Debian delta
queue appears at the end:
=over 4
=head1 HANDLING DFSG-NON-FREE MATERIAL
+This covers only DFSG-non-free material. Material which is legally
+dangerous (for example, files which are actually illegal) cannot be
+handled this way.
+
+If you encounter possibly-legally-dangerous material in the upstream
+source code you should seek advice. It is often best not to make a
+fuss on a public mailing list (at least, not at first). Instead,
+email your archive administrators. For Debian that is
+ To: dgit-owner@debian.org, ftpmaster@ftp-master.debian.org
+
=head2 When upstream tags releases in git
We create a DFSG-clean tag to import to master:
=back
-Before invoking B<git debrebase new-upstream-v0>, you should first
-determine whether it would be legally dangerous for the non-free
-material to be publicly accessible in the git history on
-B<dgit-repos>.
-
-If it would be dangerous, there is a big problem;
-in this case please consult your archive administrators
-(for Debian this is the dgit administrator dgit-owner@debian.org
-and the ftpmasters ftpmaster@ftp-master.debian.org).
-
=head2 When upstream releases only tarballs
The easiest way to handle this is to add a B<Files-Excluded> field to
I<debian/watch>. See uscan(1). Alternatively, see the I<--filter>
option detailed in gbp-import-orig(1).
-=head1 FORWARDING PATCHES UPSTREAM
-
-The basic steps are:
-
-=over 4
-
-=item 1.
-
-Create a new branch based off upstream's master branch.
-
-=item 2.
-
-git-cherry-pick(1) commits from your master branch onto your new
-branch.
-
-=item 3.
-
-Push the branch somewhere and ask upstream to merge it, or use
-git-format-patch(1) or git-request-pull(1).
-
-=back
+=head1 INCORPORATING NMUS
-For example (and it is only an example):
+In the simplest case,
=over 4
- % # fork foo.git on GitHub
- % git remote add -f fork git@github.com:spwhitton/foo.git
- % git checkout -b fix-error upstream/master
- % git config branch.fix-error.pushRemote fork
- % git cherry-pick master^2
- % git push
- % # submit pull request on GitHub
+ % dgit fetch
+ % git merge --ff-only dgit/dgit/sid
=back
-Note that when you merge an upstream release containing your forwarded
-patches, a debrebase will transparently handle "dropping" the patches
-that have been forwarded, "retaining" the ones that haven't.
+If that fails, because your branch and the NMUers work represent
+divergent branches of development, you have a number of options. Here
+we describe the two simplest.
-=head1 INCORPORATING NMUS
+=head2 Rebasing your work onto the NMU
=over 4
- % dgit pull
+ % git rebase dgit/dgit/sid
=back
For example, the NMUer might have used git-revert(1) to unapply one of
your patches. A debrebase will strip both the patch and the reversion
-from the patch series.
+from the delta queue.
+
+=head2 Manually applying the debdiff
+
+If you cannot rebase because you have already pushed to
+B<salsa.debian.org>, say, you can manually apply the NMU debdiff,
+commit and debrebase. The next B<dgit push> will require
+I<--overwrite>.
=head1 SEE ALSO
~ianmdlvl / dgit.git / blobdiff