dgit-maint-debrebase(7): notes about d/patches

[dgit.git] / dgit-maint-debrebase.7.pod

diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod
index a2ae3f8911cd0a8544fd820f74f6956a91db3de0..c615ce2eb75e49ac41252f72bdf64c30b10dd374 100644 (file)
--- a/dgit-maint-debrebase.7.pod
+++ b/dgit-maint-debrebase.7.pod
@@ -400,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
 
@@ -476,6 +476,10 @@ 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.
 
+Note that you should not try to resolve the divergent branches by
+editing files in I<debian/patches>.  Changes there would either cause
+trouble, or be overwritten by git-debrebase(1).
+
 =head2 Rebasing your work onto the NMU
 
 =over 4
@@ -488,8 +492,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
 
@@ -505,15 +509,25 @@ 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.
 
+=head2 The debian/patches directory
+
+In this workflow, I<debian/patches> is purely an output of
+git-debrebase(1).  You should not make changes there.  They will
+either cause trouble, or be ignored and overwritten by
+git-debrebase(1).
+
 =head2 Upstream branches
 
 Except in the case where upstream releases only tarballs, we do not