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 cb147b0a591b0e66a1563c1535328254b30bf363..c20a2525d1d62a0d96229f7104a4e03bec880718 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,19 +36,13 @@ 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-debrebase(7) and dgit-maint-gbp(7).

 
 =head1 INITIAL DEBIANISATION
 
 
 =head1 INITIAL DEBIANISATION
 


@@ -69,15 +65,15 @@ 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
 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
 
 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
     % git push --follow-tags -u origin master
 
 =back


@@ -94,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)).


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


@@ -151,31 +146,45 @@ 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:
+
+=over 4

 
 

-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:
+    % 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<salsa.debian.org>:

 
 =over 4
 
 
 =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
 
     % git push --follow-tags -u origin master upstream
 
 =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
 =head1 CONVERTING AN EXISTING PACKAGE
 
 This section explains how to convert an existing Debian package to


@@ -187,12 +196,24 @@ this workflow.  It should be skipped when debianising a new package.
 
     % dgit clone foo
     % cd foo
 
     % dgit clone foo
     % cd foo

+    % git remote add -f upstream https://some.upstream/foo.git

 
 =back
 
 =head2 Existing git history using another workflow
 
 
 =back
 
 =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
 
 
 =over 4
 


@@ -209,15 +230,25 @@ Then make new upstream tags available:
 
 =back
 
 
 =back
 

+=for dgit-test dpkg-source-ignores begin
+

 Now you simply need to ensure that your git HEAD is dgit-compatible,
 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.
+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>.
 
 
 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 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
 
 
 =head1 SOURCE PACKAGE CONFIGURATION
 


@@ -237,38 +268,54 @@ 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
 
 =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
 
 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


@@ -283,61 +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<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

 
 =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 -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
+    % 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

 
 

-You will need the I<debian/gbp.conf> from "When upstream releases only
-tarballs", above.
+    % git diff --stat master..1.2.3 -- . ':!debian'

 
 

-Then, either
+=back
+
+You can then review the full merge diff:

 
 =over 4
 
 
 =over 4
 

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

 
 =back
 
 
 =back
 

-or if you have a working watch file
+Once you're satisfied with what will be merged, update your package:
+
+=over 4
+
+    % git merge 1.2.3
+    % dch -v1.2.3-1 New upstream release.
+    % git add debian/changelog && git commit -m changelog
+
+=back
+
+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