dgit-maint-debrebase(7): respond to feedback

Signed-off-by: Sean Whitton <spwhitton@spwhitton.name>

1 files changed, 32 insertions, 38 deletions

diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod
index f25fe57..9e22cd1 100644
--- a/dgit-maint-debrebase.7.pod
+++ b/dgit-maint-debrebase.7.pod
@@ -116,23 +116,29 @@ it anywhere (e.g. with tools like pristine-tar(1)).
 
 =over 4
 
-It can be a good idea to compare upstream's released tarballs with the
-release tags, at least for the first upload of the package.  If they
-are different, you might need to add some additional steps to your
-I<debian/rules>, such as running autotools.
+The above assumes that you know how to build the package from git and
+that doing so is straightforward.
 
-A convenient way to perform this check is to import the tarball as
-described in the following section, using a different value for
-'upstream-tag', and then use git-diff(1) to compare the imported
-tarball to the release tag.  If they are the same, you can use
-upstream's tarball instead of running git-deborig(1).
+If, as a user of the upstream source, you usually build from upstream
+tarball releases, rather than upstream git tags, you will sometimes
+find that the git tree doesn't contain everything that is in the
+tarball.
+
+Additional build steps may be needed.  For example, you may need your
+I<debian/rules> to run autotools.
+
+You can compare the upstream tarball release, and upstream git tag,
+within git, by importing the tarball into git as described in the
+next section, using a different value for 'upstream-tag', and then
+using git-diff(1) to compare the imported tarball to the release tag.
 
 =back
 
 =head2 When upstream releases only tarballs
 
-We need a virtual upstream branch with virtual release tags.
-gbp-import-orig(1) can manage this for us.  To begin
+Because we want to work in git, we need a virtual upstream branch with
+virtual release tags.  gbp-import-orig(1) can manage this for us.  To
+begin
 
 =over 4
 
@@ -198,7 +204,6 @@ the debian/ directory containing at least one file, and does nothing
 else.>  In other words, make a commit introducing I<debian/> before
 patching the upstream source.
 
-
 =head1 CONVERTING AN EXISTING PACKAGE
 
 This section explains how to convert an existing Debian package to
@@ -236,17 +241,6 @@ corresponding to each of the quilt patches.  You can use
 
 =back
 
-or manually with gbp-pq(1):
-
-=over 4
-
-    % gbp pq import
-    % gbp pq switch
-    % git merge --ff-only patch-queue/master
-    % gbp pq drop
-
-=back
-
 Then make new upstream tags available:
 
 =over 4
@@ -255,14 +249,10 @@ Then make new upstream tags available:
 
 =back
 
-=for dgit-test dpkg-source-ignores begin
-
 Now you simply need to ensure that your git HEAD is dgit-compatible,
-i.e., it is exactly what you would get if you ran
-B<dpkg-buildpackage -i'(?:^|/)\.git(?:/|$)' -I.git -S>
-and then unpacked the resultant source package.
-
-=for dgit-test dpkg-source-ignores end
+i.e., it is exactly what you would get if you deleted .git, invoked
+B<dpkg-buildpackage -S>, and then unpacked the resultant source
+package.
 
 To achieve this, you might need to delete
 I<debian/source/local-options>.  One way to have dgit check your
@@ -272,9 +262,10 @@ The first dgit push will require I<--overwrite>.
 
 =head1 GIT CONFIGURATION
 
-This workflow does not support using B<git merge> to merge divergent
-branches of development (see "OTHER MERGES" in git-debrebase(5)).  You
-should configure git such that B<git pull> does not try to merge:
+git-debrebase does not yet support using B<git merge> to merge
+divergent branches of development (see "OTHER MERGES" in
+git-debrebase(5)).  You should configure git such that B<git pull>
+does not try to merge:
 
 =over 4
 
@@ -285,7 +276,7 @@ should configure git such that B<git pull> does not try to merge:
 Now when you pull work from other Debian contributors, git will rebase
 your work on top of theirs.
 
-If you use this repository for upstream development in addition to
+If you use this clone for upstream development in addition to
 Debian packaging work, you may not want to set this global setting.
 Instead, see the B<branch.autoSetupRebase> and
 B<branch.E<lt>nameE<gt>.rebase> settings in git-config(5).
@@ -333,12 +324,15 @@ or if you have a working watch file
 =over 4
 
     % git debrebase new-upstream-v0 1.2.3
-    % dch -v1.2.3-1 New upstream release.
-    % git add debian/changelog && git commit -m changelog
 
 =back
 
-You can now review the merge of the new upstream release:
+This invocation of git-debrebase(1) involves a git rebase.  You may
+need to resolve conflicts if the Debian delta queue does not apply
+cleanly to the new upstream source.
+
+If all went well, you can now review the merge of the new upstream
+release:
 
 =over 4
 
@@ -366,7 +360,7 @@ a tarball:
 
 Adding new patches is straightforward: just make commits touching only
 files outside of the I<debian/> directory.  You can also use tools
-like git-revert(1), git-am(1) and git-cherrypick(1).
+like git-revert(1), git-am(1) and git-cherry-pick(1).
 
 =head2 Editing patches: starting a debrebase