dgit-badcommit-fixup: Ship

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

diff --git a/dgit-maint-merge.7.pod b/dgit-maint-merge.7.pod
index f8e33b22efca328879a9836edc9b11a8ab0086f0..dc5bfa34043dd1dac121f416b3d2bc3ce444c0ad 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,15 +50,9 @@ compress orig tarballs:
 
 =head1 INITIAL DEBIANISATION
 
 
 =head1 INITIAL DEBIANISATION
 

-=head2 When upstream tags releases in git and releases identical tarballs
-
-Ideally upstream would make git tags, and tarball releases, which are
-completely identical to each other.  If this is the case then you can
-use the upstream tarballs directly.
-
-If you're not sure, use the procedure below under "When upstream
-releases only tarballs" only with a different upstream tag name.  Then
-use git diff to check that there are no differences.
+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
 
 
 =head2 When upstream tags releases in git
 


@@ -116,6 +108,23 @@ with 'gz'.
 This tarball is ephemeral and easily regenerated, so we don't commit
 it anywhere (e.g. with tools like pristine-tar(1)).
 
 This tarball is ephemeral and easily regenerated, so we don't commit
 it anywhere (e.g. with tools like pristine-tar(1)).
 

+=head3 Verifying upstream's tarball releases
+
+=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.
+
+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-archive(1).
+
+=back
+

 =head2 When upstream releases only tarballs
 
 We need a virtual upstream branch with virtual release tags.
 =head2 When upstream releases only tarballs
 
 We need a virtual upstream branch with virtual release tags.


@@ -167,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


@@ -194,7 +247,7 @@ changes to the upstream source:
 
 The Debian packaging of foo is maintained using dgit.  For the sake of
 an efficient workflow, Debian modifications to the upstream source are
 
 The Debian packaging of foo is maintained using dgit.  For the sake of
 an efficient workflow, Debian modifications to the upstream source are

-squashed into a single patch, rather than a series of quilt patches.
+squashed into a single diff, rather than a series of quilt patches.

 To obtain a patch queue for package version 1.2.3-1:
 
 =over 4
 To obtain a patch queue for package version 1.2.3-1:
 
 =over 4


@@ -256,7 +309,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


@@ -270,7 +323,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
 


@@ -306,7 +362,12 @@ We create a DFSG-clean tag to merge to master:
 Before merging the new 1.2.3+dfsg tag to master, you should first
 determine whether it would be legally dangerous for the non-free
 material to be publicly accessible in the git history on
 Before merging the new 1.2.3+dfsg tag to master, you should first
 determine whether it would be legally dangerous for the non-free
 material to be publicly accessible in the git history on

-B<dgit-repos>.  If it would be, pass B<--squash> to git-merge(1).
+B<dgit-repos>.
+
+If it would be dangerous, there is a big problem;
+in this case please consult your archive administrators
+(for Debian this is the dgit administrator dgit-owner@debian.org
+and the ftpmasters ftpmaster@ftp-master.debian.org).

 
 =head2 When upstream releases only tarballs
 
 
 =head2 When upstream releases only tarballs