docs: No longer recommend single-debian-patch anywhere

See #1018984.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

3 files changed, 40 insertions, 20 deletions

diff --git a/dgit-maint-merge.7.pod b/dgit-maint-merge.7.pod
index ddf37aa..61399ef 100644
--- a/dgit-maint-merge.7.pod
+++ b/dgit-maint-merge.7.pod
@@ -277,17 +277,37 @@ avoids introducing a new origin commit into your git history.  (This
 origin commit would represent the most recent non-dgit upload of the
 package, but this should already be represented in your git history.)
 
-=head1 SOURCE PACKAGE CONFIGURATION
+=head1 SOURCE PACKAGE AND GIT WORKING TREE CONFIGURATION
+
+=head2 dgit configuration
+
+We must tell dgit not to try to maintain
+a linear queue of patches to the upstream source:
+
+=over 4
+
+    git config dgit.default.quilt-mode single
+
+=back
+
+This affects only this one git tree;
+your other git trees for this package (and co-maintainers)
+will need it too.
+Don't set it more globally,
+because the maintainers of any other packages
+you work on, or send patches for,
+may be offended by its effects.
+
+unpleasant NMUs
 
 =head2 debian/source/options
 
-We set some source package options such that dgit can transparently
-handle the "dropping" and "refreshing" of changes to the upstream
+We set a source package option to help dpkg handle
+changes to the upstream
 source:
 
 =over 4
 
-    single-debian-patch
     auto-commit
 
 =back
@@ -295,7 +315,7 @@ source:
 You don't need to create this file if you are using the version 1.0
 source package format.
 
-=head2 Sample text for debian/source/patch-header
+=head2 Sample text for debian/README.source
 
 It is a good idea to explain how a user can obtain a breakdown of the
 changes to the upstream source:
@@ -327,15 +347,6 @@ A single combined diff, containing all the changes, follows.
 
 =back
 
-If you are using the version 1.0 source package format, this text
-should be added to README.source instead.  The version 1.0 source
-package format ignores debian/source/patch-header.
-
-If you're using the version 3.0 (quilt) source package format, you
-could add this text to README.source instead of
-debian/source/patch-header, but this might distract from more
-important information present in README.source.
-
 =head1 BUILDING AND UPLOADING
 
 Use B<dgit build>, B<dgit sbuild>, B<dgit pbuilder>, B<dgit
@@ -345,7 +356,7 @@ error message explaining what you should do.  If it's not clear, file
 a bug against dgit.  Remember to pass I<--new> for the first upload.
 
 If you want to upload with git-debpush(1), for the first upload you
-should pass the B<--quilt=smash> quilt mode option (see
+should pass the B<--quilt=single> quilt mode option (see
 git-debpush(1)).
 
 As another alternative to B<dgit build> and friends, you can use a
diff --git a/dgit.1 b/dgit.1
index bc5649a..39649c0 100644
--- a/dgit.1
+++ b/dgit.1
@@ -862,6 +862,15 @@ When fixing up source format `3.0 (quilt)' metadata,
 delete all the existing patches, and then
 generate a single patch for all the changes made in git.
 This is not a good idea for an NMU in Debian.
+
+Use this instead of the
+.B single-debian-patch
+dpkg-source format option.
+That dpkg-source option cannot handle certain changes to the tree
+that dpkg-source otherwise permits,
+and in some cases it can generate strange source packages
+that dpkg-source appears to accept
+but which become corrupted when people later try to modify them.
 .TP
 .BR --quilt=nofix
 Check whether source format `3.0 (quilt)' metadata would need fixing
diff --git a/dgit.7 b/dgit.7
index d1e5c7e..4144ed6 100644
--- a/dgit.7
+++ b/dgit.7
@@ -373,13 +373,13 @@ Your appropriate response depends on the cause and the context.
 If you have been freely merging your git branch
 and do not need need a pretty linear patch queue,
 you can use
-.B --quilt=smash
-(or use the
-.B 1.0
+.BR --quilt=single
 or
+.BR --quilt=smash .
+(Don't use
+the
 .B single-debian-patch
-source formats; see
-.BR dpkg-source(1) .)
+dpkg source format option; it has strange properties.)
 If you want a pretty linear series,
 and this message is unexpected,
 it can mean that you have unwittingly committed changes