test suite: gdr-unprocessable: new test

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

diff --git a/dgit-maint-merge.7.pod b/dgit-maint-merge.7.pod
index cfbe1c35fd322aa00d20ee080fd1292f09707a64..c20a2525d1d62a0d96229f7104a4e03bec880718 100644 (file)
--- a/dgit-maint-merge.7.pod
+++ b/dgit-maint-merge.7.pod
@@ -42,7 +42,7 @@ or which you aren't going to be able to upstream soon,
 it might be preferable to
 maintain the delta as a rebasing patch series.
 For such a workflow see for example
-dgit-maint-gbp(7).
+dgit-maint-debrebase(7) and dgit-maint-gbp(7).
 
 =head1 INITIAL DEBIANISATION
 
@@ -68,12 +68,12 @@ been tagged '1.2.2' by upstream.
 The final command detaches your master branch from the upstream remote,
 so that git doesn't try to push anything there, or merge unreleased
 upstream commits.  If you want to maintain a copy of your packaging
-branch on B<alioth.debian.org> in addition to B<dgit-repos>, you can
+branch on B<salsa.debian.org> in addition to B<dgit-repos>, you can
 do something like this:
 
 =over 4
 
-    % git remote add -f origin git.debian.org:/git/collab-maint/foo.git
+    % git remote add -f origin salsa.debian.org:Debian/foo.git
     % git push --follow-tags -u origin master
 
 =back
@@ -173,11 +173,11 @@ Then we can import the upstream version:
 
 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>:
+it somewhere.  The usual choice is B<salsa.debian.org>:
 
 =over 4
 
-    % git remote add -f origin git.debian.org:/git/collab-maint/foo.git
+    % git remote add -f origin salsa.debian.org:Debian/foo.git
     % git push --follow-tags -u origin master upstream
 
 =back
@@ -211,6 +211,8 @@ and obtain the corresponding orig.tar from the archive:
     % cd foo
     % origtargz
 
+=back
+
 Now dump any existing patch queue:
 
 =over 4
@@ -241,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
 
@@ -293,17 +300,22 @@ 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
 
-Use B<dgit build>, B<dgit sbuild>, B<dgit build-source>, and B<dgit
-push> as detailed in dgit(1).  If any command fails, dgit will provide
-a carefully-worded 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.
+Use B<dgit build>, B<dgit sbuild>, B<dgit pbuilder>, B<dgit
+cowbuilder>, B<dgit push-source>, and B<dgit push> as detailed in
+dgit(1).  If any command fails, dgit will provide a carefully-worded
+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.
 
 As an alternative to B<dgit build> and friends, you can use a tool
 like gitpkg(1).  This works because like dgit, gitpkg(1) enforces that
@@ -332,7 +344,7 @@ to git), you can just run dpkg-buildpackage(1) or debuild(1) instead.
 
 You will need the I<debian/gbp.conf> from "When upstream releases only
 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
+pushed this to B<salsa.debian.org>.  You will need to clone or fetch
 from there, instead of relying on B<dgit clone>/B<dgit fetch> alone.
 
 Then, either