Dgit.pm: Introduce $debugcmd_when_debuglevel

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

diff --git a/dgit-maint-merge.7.pod b/dgit-maint-merge.7.pod
index f8e33b22efca328879a9836edc9b11a8ab0086f0..c20a2525d1d62a0d96229f7104a4e03bec880718 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


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


@@ -36,31 +36,19 @@ 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
 

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


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


@@ -102,20 +90,36 @@ 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)).
 

+=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-deborig(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.


@@ -142,31 +146,110 @@ 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
+
+Then we can import the upstream version:
+
+=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<salsa.debian.org>:
+
+=over 4
+
+    % git remote add -f origin salsa.debian.org:Debian/foo.git
+    % 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.
 
 
 =back
 
 You are now ready to proceed as above, making commits to both the
 upstream source and the I<debian/> directory.
 

-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:
+=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
 
 
 =over 4
 

-    % git remote add -f origin git.debian.org:/git/collab-maint/foo.git
-    % git push --follow-tags -u origin master upstream
+    % 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
 
 
 =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


@@ -185,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 patch, 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


@@ -231,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<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 ../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

 
 

-Either
+    % git merge-tree `git merge-base master 1.2.3` master 1.2.3 | $PAGER
+
+=back
+
+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
 


@@ -306,7 +423,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