changelog: Mention #850519 re docs updates

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

diff --git a/dgit-maint-merge.7.pod b/dgit-maint-merge.7.pod
index f785af7ad97282fb47f14c5e70441fc0ea903799..245be4c937a744cffd16bdc7a8f709b056cd1ce3 100644 (file)
--- a/dgit-maint-merge.7.pod
+++ b/dgit-maint-merge.7.pod
@@ -16,8 +16,6 @@ Git histories should be the non-linear histories produced by
 git-merge(1), preserving all information about divergent development
 that was later brought together.
 
 git-merge(1), preserving all information about divergent development
 that was later brought together.
 

-If you prefer linear histories, see dgit-maint-rebase(7).
-

 =item
 
 Maintaining convenient and powerful git workflows takes priority over
 =item
 
 Maintaining convenient and powerful git workflows takes priority over


@@ -52,6 +50,10 @@ compress orig tarballs:
 
 =head1 INITIAL DEBIANISATION
 
 
 =head1 INITIAL DEBIANISATION
 

+This section explains how to start using this workflow with a new
+package.  It should be skipped when converting an existing package to
+this workflow.
+

 =head2 When upstream tags releases in git
 
 Suppose that the latest stable upstream release is 1.2.2, and this has
 =head2 When upstream tags releases in git
 
 Suppose that the latest stable upstream release is 1.2.2, and this has


@@ -174,6 +176,50 @@ branches:
 
 =back
 
 
 =back
 

+=head1 CONVERTING AN EXISTING PACKAGE
+
+This section explains how to convert an existing Debian package to
+this workflow.  It should be skipped when debianising a new package.
+
+=head2 No existing git history
+
+=over 4
+
+    % dgit clone foo
+    % cd foo
+    % git remote add -f upstream https://some.upstream/foo.git
+
+=back
+
+=head2 Existing git history using another workflow
+
+First, dump any existing patch queue:
+
+=over 4
+
+    % git rm -rf debian/patches
+    % git commit -m "drop existing quilt patch queue"
+
+=back
+
+Then make new upstream tags available:
+
+=over 4
+
+    % git remote add -f upstream https://some.upstream/foo.git
+
+=back
+
+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.
+
+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>.
+

 =head1 SOURCE PACKAGE CONFIGURATION
 
 =head2 debian/source/options
 =head1 SOURCE PACKAGE CONFIGURATION
 
 =head2 debian/source/options


@@ -192,7 +238,7 @@ source:
 You don't need to create this file if you are using the version 1.0
 source package format.
 
 You don't need to create this file if you are using the version 1.0
 source package format.
 

-=head2 Sample text for README.source
+=head2 Sample text for debian/source/patch-header

 
 It is a good idea to explain how a user can obtain a break down of the
 changes to the upstream source:
 
 It is a good idea to explain how a user can obtain a break down of the
 changes to the upstream source:


@@ -217,6 +263,10 @@ See dgit(1), dgit(7) and dgit-maint-merge(7) for more information.
 
 =back
 
 
 =back
 

+Alternatively, this text could be added to README.source. However,
+this might distract from more important information present in the
+latter file.
+

 =head1 BUILDING AND UPLOADING
 
 Use B<dgit build>, B<dgit sbuild>, B<dgit build-source>, and B<dgit
 =head1 BUILDING AND UPLOADING
 
 Use B<dgit build>, B<dgit sbuild>, B<dgit build-source>, and B<dgit


@@ -263,7 +313,7 @@ Once you're satisfied with what will be merged, update your package:
 
 =over 4
 
 
 =over 4
 

-    % git archive ../foo_1.2.3.orig.tar.xz 1.2.3
+    % git archive -o ../foo_1.2.3.orig.tar.xz 1.2.3

     % git merge 1.2.3
     % dch -v1.2.3-1 New upstream release.
     % git add debian/changelog && git commit -m changelog
     % git merge 1.2.3
     % dch -v1.2.3-1 New upstream release.
     % git add debian/changelog && git commit -m changelog


@@ -277,7 +327,10 @@ Again, if you are using the version 1.0 source package format, replace
 
 =head2 When upstream releases only tarballs
 
 
 =head2 When upstream releases only tarballs
 

-Either
+You will need the I<debian/gbp.conf> from "When upstream releases only
+tarballs", above.
+
+Then, either

 
 =over 4
 
 
 =over 4