|author||Sean Whitton <email@example.com>||2018-04-03 10:16:38 -0700|
|committer||Sean Whitton <firstname.lastname@example.org>||2018-04-19 09:41:24 -0700|
dgit-maint-debrebase(7): begin incorporating feedback
Signed-off-by: Sean Whitton <email@example.com>
1 files changed, 38 insertions, 69 deletions
diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod
index 0b4e756..3c454e0 100644
@@ -8,8 +8,8 @@ This document describes elements of a workflow for maintaining a
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:
@@ -18,8 +18,9 @@ Some advantages of this workflow:
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).
+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).
@@ -37,23 +38,28 @@ Provide your full git history in a standard format on B<dgit-repos>,
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)).
+Minimise the amount you need to know about 3.0 (quilt) in order to
+maintain Debian source packages which use that format.
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
+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
+=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.
@@ -212,8 +218,15 @@ and obtain the corresponding orig.tar from the archive:
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
+corresponding to each of the quilt patches. You can use
+ git debrebase convert-from-gbp
+or manually with gbp-pq(1):
@@ -348,14 +361,6 @@ can perform a non-interactive rebase like this:
- % git debrebase -- --autosquash
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,
@@ -363,10 +368,13 @@ using git-rebase(1). For example,
% git debrebase launder
- % git rebase -i HEAD^5 # there are 4 Debian patches
+ % git rebase -i HEAD~5 # there are 4 Debian patches
+If you take this approach, you should be very careful not to start the
+rebase earlier than the beginning of the patch queue.
=head2 Editing patches: finishing a debrebase
After completing the git rebase, your branch will not be a
@@ -380,6 +388,7 @@ git remote such as B<salsa.debian.org>,
+ % git debrebase launder
% git debrebase stitch
@@ -436,6 +445,16 @@ Note that this will introduce a new pseudomerge.
=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: firstname.lastname@example.org, email@example.com
=head2 When upstream tags releases in git
We create a DFSG-clean tag to import to master:
@@ -451,16 +470,6 @@ We create a DFSG-clean tag to import to master:
-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
-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 firstname.lastname@example.org
-and the ftpmasters email@example.com).
=head2 When upstream releases only tarballs
The easiest way to handle this is to add a B<Files-Excluded> field to
@@ -468,46 +477,6 @@ I<debian/copyright>, and a B<uversionmangle> setting in
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:
-Create a new branch based off upstream's master branch.
-git-cherry-pick(1) commits from your master branch onto your new
-Push the branch somewhere and ask upstream to merge it, or use
-git-format-patch(1) or git-request-pull(1).
-For example (and it is only an example):
- % # fork foo.git on GitHub
- % git remote add -f fork firstname.lastname@example.org: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
-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.
=head1 INCORPORATING NMUS