git-debrebase: breakwater_of: permit unclean to be an fproblem

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

diff --git a/dgit-maint-merge.7.pod b/dgit-maint-merge.7.pod
index ed7cdc060fac83be63547f2f9e60c605a8a13490..2674d66dee14de119ff5559c52a381244362c02f 100644 (file)
--- a/dgit-maint-merge.7.pod
+++ b/dgit-maint-merge.7.pod
@@ -171,12 +171,9 @@ Then we can import the upstream version:
 
 =back
 
-You are now ready to proceed as above, making commits to both the
-upstream source and the I<debian/> directory.
-
-If you want to maintain a copy of your repository on
-B<alioth.debian.org>, you should push both the origin and the upstream
-branches:
+Our upstream branch cannot be pushed to B<dgit-repos>, but since we
+will need it whenever we import a new upstream version, we must push
+it somewhere.  The usual choice is B<alioth.debian.org>:
 
 =over 4
 
@@ -185,6 +182,9 @@ branches:
 
 =back
 
+You are now ready to proceed as above, making commits to both the
+upstream source and the I<debian/> directory.
+
 =head1 CONVERTING AN EXISTING PACKAGE
 
 This section explains how to convert an existing Debian package to
@@ -202,7 +202,18 @@ this workflow.  It should be skipped when debianising a new package.
 
 =head2 Existing git history using another workflow
 
-First, dump any existing patch queue:
+First, if you don't already have the git history locally, clone it,
+and obtain the corresponding orig.tar from the archive:
+
+=over 4
+
+    % git clone git.debian.org:collab-maint/foo
+    % cd foo
+    % origtargz
+
+=back
+
+Now dump any existing patch queue:
 
 =over 4
 
@@ -232,7 +243,12 @@ To achieve this, you might need to delete
 I<debian/source/local-options>.  One way to have dgit check your
 progress is to run B<dgit build-source>.
 
-The first dgit push will require I<--overwrite>.
+The first dgit push will require I<--overwrite>.  If this is the first
+ever dgit push of the package, consider passing
+I<--deliberately-not-fast-forward> instead of I<--overwrite>.  This
+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
 
@@ -284,9 +300,14 @@ A single combined diff, containing all the changes, follows.
 
 =back
 
-Alternatively, this text could be added to README.source. However,
-this might distract from more important information present in the
-latter file.
+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
 
@@ -322,7 +343,9 @@ to git), you can just run dpkg-buildpackage(1) or debuild(1) instead.
 =head3 When upstream releases only tarballs
 
 You will need the I<debian/gbp.conf> from "When upstream releases only
-tarballs", above.
+tarballs", above.  You will also need your upstream branch.  Above, we
+pushed this to B<alioth.debian.org>.  You will need to clone or fetch
+from there, instead of relying on B<dgit clone>/B<dgit fetch> alone.
 
 Then, either