git-debrebase: test suite: gdr-import-dgit: test a new upstream non-gdr upload too

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

diff --git a/dgit-maint-merge.7.pod b/dgit-maint-merge.7.pod
index 8794d1d0539287fcb527ea4599ccfb622d9deabc..2674d66dee14de119ff5559c52a381244362c02f 100644 (file)
--- a/dgit-maint-merge.7.pod
+++ b/dgit-maint-merge.7.pod
@@ -23,7 +23,9 @@ the usefulness of the raw Debian source package.  The Debian archive
 is thought of as an output format.
 
 For example, we don't spend time curating a series of quilt patches.
 is thought of as an output format.
 
 For example, we don't spend time curating a series of quilt patches.

-However, the information such a series would contain is readily
+However,
+in straightforward cases,
+the information such a series would contain is readily

 available from B<dgit-repos>.
 
 =item
 available from B<dgit-repos>.
 
 =item


@@ -34,22 +36,20 @@ that upstream makes available for download.
 
 =back
 
 
 =back
 

-=head1 GIT CONFIGURATION
-
-Add the following to your ~/.gitconfig to teach git-archive(1) how to
-compress orig tarballs:
-
-=over 4
-
-    [tar "tar.xz"]
-       command = xz -c
-    [tar "tar.gz"]
-       command = gzip -c
-
-=back
+This workflow is less suitable for some packages.
+When the Debian delta contains multiple pieces which interact,
+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).

 
 =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


@@ -65,7 +65,7 @@ been tagged '1.2.2' by upstream.
 
 =back
 
 
 =back
 

-The final command detachs your master branch from the upstream remote,
+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
 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


@@ -90,16 +90,15 @@ unless you also happen to be involved in upstream development.  We
 work with upstream tags rather than any branches, except when
 forwarding patches (see FORWARDING PATCHES UPSTREAM, below).
 
 work with upstream tags rather than any branches, except when
 forwarding patches (see FORWARDING PATCHES UPSTREAM, below).
 

-Finally, you need an orig tarball.  Generate one with git-archive(1):
+Finally, you need an orig tarball:

 
 =over 4
 
 
 =over 4
 

-    % git archive -o ../foo_1.2.2.orig.tar.xz 1.2.2
+    % git deborig

 
 =back
 
 
 =back
 

-If you are using the version 1.0 source package format, replace 'xz'
-with 'gz'.
+See git-deborig(1) if this fails.

 
 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)).


@@ -117,7 +116,7 @@ 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
 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).
+upstream's tarball instead of running git-deborig(1).

 
 =back
 
 
 =back
 


@@ -147,23 +146,34 @@ Now create I<debian/gbp.conf>:
     pristine-tar = False
     pristine-tar-commit = False
 
     pristine-tar = False
     pristine-tar-commit = False
 

+    [import-orig]
+    merge-mode = merge
+

 =back
 
 =back
 

-Then we can import the upstream version:
+gbp-import-orig(1) requires a pre-existing upstream branch:

 
 =over 4
 
     % git add debian/gbp.conf && git commit -m "create gbp.conf"
 
 =over 4
 
     % git add debian/gbp.conf && git commit -m "create gbp.conf"

-    % gbp import-orig ../foo_1.2.2.orig.tar.xz
+    % git checkout --orphan upstream
+    % git rm -rf .
+    % git commit --allow-empty -m "initial, empty branch for upstream source"
+    % git checkout -f master

 
 =back
 
 
 =back
 

-You are now ready to proceed as above, making commits to both the
-upstream source and the I<debian/> directory.
+Then we can import the upstream version:

 
 

-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:
+=over 4
+
+    % gbp import-orig --merge-mode=replace ../foo_1.2.2.orig.tar.xz
+
+=back
+
+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
 
 
 =over 4
 


@@ -172,6 +182,74 @@ branches:
 
 =back
 
 
 =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
+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, 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
+
+    % 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
+
+=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
+
+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>.  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
 
 =head2 debian/source/options
 =head1 SOURCE PACKAGE CONFIGURATION
 
 =head2 debian/source/options


@@ -190,31 +268,47 @@ 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
+It is a good idea to explain how a user can obtain a breakdown of the

 changes to the upstream source:
 
 =over 4
 
 changes to the upstream source:
 
 =over 4
 

-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 diff, rather than a series of quilt patches.
-To obtain a patch queue for package version 1.2.3-1:
+The Debian packaging of foo is maintained in git,
+using the merging workflow described in dgit-maint-merge(7).
+There isn't a patch queue that can be represented as a quilt series.
+
+A detailed breakdown of the changes is available from their
+canonical representation -
+git commits in the packaging repository.
+For example, to see the changes made by the Debian maintainer in the
+first upload of upstream version 1.2.3, you could use:

 
 =over 4
 
 
 =over 4
 

-    # apt-get install dgit
-    % dgit clone foo
+    % git clone https://git.dgit.debian.org/foo

     % cd foo
     % git log --oneline 1.2.3..debian/1.2.3-1 -- . ':!debian'
 
 =back
 
     % cd foo
     % git log --oneline 1.2.3..debian/1.2.3-1 -- . ':!debian'
 
 =back
 

-See dgit(1), dgit(7) and dgit-maint-merge(7) for more information.
+(If you have dgit, use `dgit clone foo`,
+rather than plain `git clone`.)
+
+A single combined diff, containing all the changes, follows.

 
 =back
 
 
 =back
 

+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
 =head1 BUILDING AND UPLOADING
 
 Use B<dgit build>, B<dgit sbuild>, B<dgit build-source>, and B<dgit


@@ -236,58 +330,76 @@ to git), you can just run dpkg-buildpackage(1) or debuild(1) instead.
 
 =head1 NEW UPSTREAM RELEASES
 
 
 =head1 NEW UPSTREAM RELEASES
 

-=head2 When upstream tags releases in git
+=head2 Obtaining the release

 
 

-It's a good idea to preview the merge of the new upstream release.
-First, just check for any new or deleted files that may need
-accounting for in your copyright file:
+=head3 When upstream tags releases in git

 
 =over 4
 
     % git remote update
 
 =over 4
 
     % git remote update

-    % git diff --stat master..1.2.3 -- . ':!debian'

 
 =back
 
 
 =back
 

-You can then review the full merge diff:
+=head3 When upstream releases only tarballs
+
+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
+from there, instead of relying on B<dgit clone>/B<dgit fetch> alone.
+
+Then, either

 
 =over 4
 
 
 =over 4
 

-    % git merge-tree `git merge-base master 1.2.3` master 1.2.3 | $PAGER
+    % gbp import-orig --no-merge ../foo_1.2.3.orig.tar.xz

 
 =back
 
 
 =back
 

-Once you're satisfied with what will be merged, update your package:
+or if you have a working watch file

 
 =over 4
 
 
 =over 4
 

-    % git archive ../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
+    % gbp import-orig --no-merge --uscan

 
 =back
 
 
 =back
 

-and you are ready to try a build.
+=head2 Reviewing & merging the release

 
 

-Again, if you are using the version 1.0 source package format, replace
-'xz' with 'gz'.
+It's a good idea to preview the merge of the new upstream release.
+First, just check for any new or deleted files that may need
+accounting for in your copyright file:

 
 

-=head2 When upstream releases only tarballs
+=over 4
+
+    % git diff --stat master..1.2.3 -- . ':!debian'
+
+=back
+
+You can then review the full merge diff:
+
+=over 4
+
+    % git merge-tree `git merge-base master 1.2.3` master 1.2.3 | $PAGER
+
+=back

 
 

-Either
+Once you're satisfied with what will be merged, update your package:

 
 =over 4
 
 
 =over 4
 

-    % gbp import-orig ../foo_1.2.2.orig.tar.xz
+    % git merge 1.2.3
+    % dch -v1.2.3-1 New upstream release.
+    % git add debian/changelog && git commit -m changelog

 
 =back
 
 
 =back
 

-or if you have a working watch file
+If you obtained a tarball from upstream, you are ready to try a build.
+If you merged a git tag from upstream, you will first need to generate
+a tarball:

 
 =over 4
 
 
 =over 4
 

-    % gbp import-orig --uscan
+    % git deborig

 
 =back
 
 
 =back