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 f5023e849ba5c6c271069e713a929bdf9c3974a4..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
@@ -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