chiark / gitweb /
dgit-maint-debrebase(7): improve advice about minimising stitches
[dgit.git] / dgit-maint-debrebase.7.pod
index 9e22cd134a3f5ef19b0b4424454d083529c44d48..601b8e92bd6a963c3e786552ec8c8cd3227802d1 100644 (file)
@@ -232,8 +232,8 @@ 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.  You can use
+If your tree is patches-unapplied, some conversion work is needed.
+You can use
 
 =over 4
 
@@ -354,6 +354,10 @@ a tarball:
 
 =back
 
+=head1 EDITING THE DEBIAN PACKAGING
+
+Just make commits on master that change the contents of I<debian/>.
+
 =head1 EDITING THE DELTA QUEUE
 
 =head2 Adding new patches
@@ -369,7 +373,7 @@ edit, re-order and delete patches.  Run
 
 =over 4
 
-    % git debrebase
+    % git debrebase -i
 
 =back
 
@@ -396,8 +400,8 @@ git remote such as B<salsa.debian.org>,
 Note that each time you conclude 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 delta queue that you think will be
-needed for this upload in a single debrebase, so that there is a
-single debrebase stitch.
+needed for this editing session in a single debrebase, so that there
+is a single debrebase stitch.
 
 =head1 BUILDING AND UPLOADING
 
@@ -413,7 +417,7 @@ delta queue appears right at the tip of the branch you will push:
 
 =over 4
 
-    % git debrebase launder
+    % git debrebase
     % dgit push-source
 
 =back
@@ -484,8 +488,8 @@ If the NMUer added new commits modifying the upstream source, you will
 probably want to debrebase before your next upload to tidy those up.
 
 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 delta queue.
+your patches.  A debrebase can be used to strip both the patch and the
+reversion from the delta queue.
 
 =head2 Manually applying the debdiff
 
@@ -501,12 +505,15 @@ I<--overwrite>.
 Above we noted that each time you conclude a debrebase, you introduce
 a pseudomerge into your git history, which may make it harder to read.
 
-A convention you can use to minimise the number of pseudomerges is to
-debrebase only right before you upload.
+A simple convention you can use to minimise the number of pseudomerges
+is to B<git debrebase conclude> only right before you upload or push
+to B<salsa.debian.org>.
 
-Before that point, instead of editing the existing delta queue, you
+It is possible to reduce the number of pseudomerges further by
+derebasing only (i) when importing a new release, and (ii) right
+before uploading.  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
+upstream source to the required state.  You can push and pull to and
 from B<salsa.debian.org> during this.  Just before uploading, you
 debrebase, once, to tidy everything up.
 
@@ -518,10 +525,8 @@ involved in upstream development).  We work with upstream tags rather
 than any branches, except temporary branches used to prepare patches
 for forwarding upstream, for example.
 
-The thought behind this is that branches are things to which one
-expects to commit, while tags are immutable points in history.  From
-the Debian point of the view, the upstream source is immutable.  It's
-our packaging to which we expect to commit.
+The thought behind this is that from Debian's point of view, upstream
+releases are immutable points in history, better represented by tags.
 
 =head2 The first ever dgit push
 
@@ -534,11 +539,11 @@ package, but this should already be represented in your git history.)
 =head2 Alternative ways to start a debrebase
 
 Above we started an interactive debrebase by invoking git-debrebase(1)
-without any arguments, i.e.
+like this:
 
 =over 4
 
-    % git debrebase
+    % git debrebase -i
 
 =back
 
@@ -563,7 +568,7 @@ using git-rebase(1) directly.  For example,
 =back
 
 If you take this approach, you should be very careful not to start the
-rebase earlier than the beginning of the delta queue.
+rebase too early.
 
 =head1 SEE ALSO