chiark / gitweb /
dgit-maint-debrebase(7): begin incorporating feedback
authorSean Whitton <spwhitton@spwhitton.name>
Tue, 3 Apr 2018 17:16:38 +0000 (10:16 -0700)
committerSean Whitton <spwhitton@spwhitton.name>
Thu, 19 Apr 2018 16:41:24 +0000 (09:41 -0700)
Signed-off-by: Sean Whitton <spwhitton@spwhitton.name>
dgit-maint-debrebase.7.pod

index 0b4e756..3c454e0 100644 (file)
@@ -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:
 =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).
+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
 
@@ -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)).
 
+=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.
 
@@ -212,8 +218,15 @@ and obtain the corresponding orig.tar from the archive:
 =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
 
@@ -348,14 +361,6 @@ can perform a non-interactive rebase like this:
 
 =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,
@@ -363,10 +368,13 @@ 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 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>,
 
 =over 4
 
+    % git debrebase launder
     % git debrebase stitch
 
 =back
@@ -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: 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:
@@ -451,16 +470,6 @@ 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
@@ -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:
-
-=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
-
-For example (and it is only an example):
-
-=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
-
-=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.
-
 =head1 INCORPORATING NMUS
 
 =over 4