diff options
author | Ian Jackson <ijackson@chiark.greenend.org.uk> | 2022-09-03 14:03:53 +0100 |
---|---|---|
committer | Ian Jackson <ijackson@chiark.greenend.org.uk> | 2022-09-03 20:14:26 +0100 |
commit | 05c51f36fed13475444083e587554557a3c8de12 (patch) | |
tree | 74179eb085002431d5d45988f2419a24e48d8475 | |
parent | ceb25938005b5bdf130425110e075a5cd7411410 (diff) |
docs: No longer recommend single-debian-patch anywhere
See #1018984.
Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
-rw-r--r-- | dgit-maint-merge.7.pod | 41 | ||||
-rw-r--r-- | dgit.1 | 9 | ||||
-rw-r--r-- | dgit.7 | 10 |
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 @@ -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 @@ -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 |