chiark / gitweb /
changelog: start 6.1
[dgit.git] / dgit-maint-debrebase.7.pod
index f25fe57..e492768 100644 (file)
@@ -116,23 +116,29 @@ it anywhere (e.g. with tools like pristine-tar(1)).
 
 =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.
+The above assumes that you know how to build the package from git and
+that doing so is straightforward.
 
-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).
+If, as a user of the upstream source, you usually build from upstream
+tarball releases, rather than upstream git tags, you will sometimes
+find that the git tree doesn't contain everything that is in the
+tarball.
+
+Additional build steps may be needed.  For example, you may need your
+I<debian/rules> to run autotools.
+
+You can compare the upstream tarball release, and upstream git tag,
+within git, by importing the tarball into git as described in the
+next section, using a different value for 'upstream-tag', and then
+using git-diff(1) to compare the imported tarball to the release tag.
 
 =back
 
 =head2 When upstream releases only tarballs
 
-We need a virtual upstream branch with virtual release tags.
-gbp-import-orig(1) can manage this for us.  To begin
+Because we want to work in git, we need a virtual upstream branch with
+virtual release tags.  gbp-import-orig(1) can manage this for us.  To
+begin
 
 =over 4
 
@@ -198,7 +204,6 @@ the debian/ directory containing at least one file, and does nothing
 else.>  In other words, make a commit introducing I<debian/> before
 patching the upstream source.
 
-
 =head1 CONVERTING AN EXISTING PACKAGE
 
 This section explains how to convert an existing Debian package to
@@ -227,8 +232,8 @@ and obtain the corresponding orig.tar from the archive:
 
 =back
 
-If your tree is patches-unapplied, you will need to make a commit
-corresponding to each of the quilt patches.  You can use
+If your tree is patches-unapplied, some conversion work is needed.
+You can use
 
 =over 4
 
@@ -236,17 +241,6 @@ corresponding to each of the quilt patches.  You can use
 
 =back
 
-or manually with gbp-pq(1):
-
-=over 4
-
-    % gbp pq import
-    % gbp pq switch
-    % git merge --ff-only patch-queue/master
-    % gbp pq drop
-
-=back
-
 Then make new upstream tags available:
 
 =over 4
@@ -255,14 +249,10 @@ Then make new upstream tags available:
 
 =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
+i.e., it is exactly what you would get if you deleted .git, invoked
+B<dpkg-buildpackage -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
@@ -272,9 +262,10 @@ The first dgit push will require I<--overwrite>.
 
 =head1 GIT CONFIGURATION
 
-This workflow does not support using B<git merge> to merge divergent
-branches of development (see "OTHER MERGES" in git-debrebase(5)).  You
-should configure git such that B<git pull> does not try to merge:
+git-debrebase(1) does not yet support using B<git merge> to merge
+divergent branches of development (see "OTHER MERGES" in
+git-debrebase(5)).  You should configure git such that B<git pull>
+does not try to merge:
 
 =over 4
 
@@ -285,7 +276,7 @@ should configure git such that B<git pull> does not try to merge:
 Now when you pull work from other Debian contributors, git will rebase
 your work on top of theirs.
 
-If you use this repository for upstream development in addition to
+If you use this clone for upstream development in addition to
 Debian packaging work, you may not want to set this global setting.
 Instead, see the B<branch.autoSetupRebase> and
 B<branch.E<lt>nameE<gt>.rebase> settings in git-config(5).
@@ -332,13 +323,16 @@ or if you have a working watch file
 
 =over 4
 
-    % git debrebase new-upstream-v0 1.2.3
-    % dch -v1.2.3-1 New upstream release.
-    % git add debian/changelog && git commit -m changelog
+    % git debrebase new-upstream 1.2.3
 
 =back
 
-You can now review the merge of the new upstream release:
+This invocation of git-debrebase(1) involves a git rebase.  You may
+need to resolve conflicts if the Debian delta queue does not apply
+cleanly to the new upstream source.
+
+If all went well, you can now review the merge of the new upstream
+release:
 
 =over 4
 
@@ -360,13 +354,17 @@ a tarball:
 
 =back
 
+=head1 EDITING THE DEBIAN PACKAGING
+
+Just make commits on master that change the contents of I<debian/>.
+
 =head1 EDITING THE DELTA QUEUE
 
 =head2 Adding new patches
 
 Adding new patches is straightforward: just make commits touching only
 files outside of the I<debian/> directory.  You can also use tools
-like git-revert(1), git-am(1) and git-cherrypick(1).
+like git-revert(1), git-am(1) and git-cherry-pick(1).
 
 =head2 Editing patches: starting a debrebase
 
@@ -375,7 +373,7 @@ edit, re-order and delete patches.  Run
 
 =over 4
 
-    % git debrebase
+    % git debrebase -i
 
 =back
 
@@ -402,8 +400,8 @@ git remote such as B<salsa.debian.org>,
 Note that each time you conclude a debrebase you introduce a
 pseudomerge into your git history, which may make it harder to read.
 Try to do all of the editing of the delta queue that you think will be
-needed for this upload in a single debrebase, so that there is a
-single debrebase stitch.
+needed for this editing session in a single debrebase, so that there
+is a single debrebase stitch.
 
 =head1 BUILDING AND UPLOADING
 
@@ -419,7 +417,7 @@ delta queue appears right at the tip of the branch you will push:
 
 =over 4
 
-    % git debrebase launder
+    % git debrebase
     % dgit push-source
 
 =back
@@ -431,9 +429,11 @@ you're using that.
 
 =head1 HANDLING DFSG-NON-FREE MATERIAL
 
-This covers only DFSG-non-free material.  Material which is legally
-dangerous (for example, files which are actually illegal) cannot be
-handled this way.
+=head2 Illegal material
+
+Here we explain how to handle material that is merely DFSG-non-free.
+Material which is legally dangerous (for example, files which are
+actually illegal) cannot be handled this way.
 
 If you encounter possibly-legally-dangerous material in the upstream
 source code you should seek advice.  It is often best not to make a
@@ -441,22 +441,51 @@ fuss on a public mailing list (at least, not at first).  Instead,
 email your archive administrators.  For Debian that is
  To: dgit-owner@debian.org, ftpmaster@ftp-master.debian.org
 
-=head2 When upstream tags releases in git
+=head2 DFSG-non-free: When upstream tags releases in git
 
-We create a DFSG-clean tag to import to master:
+Our approach is to maintain a DFSG-clean upstream branch, and create
+tags on this branch for each release that we want to import.  We then
+import those tags per "Importing the release", above.
+
+For the first upstream release that requires DFSG filtering:
 
 =over 4
 
-    % git checkout -b pre-dfsg 1.2.3
+    % git checkout -b upstream-dfsg 1.2.3
     % git rm evil.bin
     % git commit -m "upstream version 1.2.3 DFSG-cleaned"
     % git tag -s 1.2.3+dfsg
     % git checkout master
-    % git branch -D pre-dfsg
+    % # proceed with "Importing the release" on 1.2.3+dfsg tag
 
 =back
 
-=head2 When upstream releases only tarballs
+And for subsequent releases (whether or not they require filtering):
+
+=over 4
+
+    % git checkout upstream-dfsg
+    % git merge 1.2.4
+    % git rm further-evil.bin # if needed
+    % git commit -m "upstream version 1.2.4 DFSG-cleaned" # if needed
+    % git tag -s 1.2.4+dfsg
+    % git checkout master
+    % # proceed with "Importing the release" on 1.2.4+dfsg tag
+
+=back
+
+Our upstream-dfsg 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.  Assuming that you have already set up an origin
+remote per the above,
+
+=over 4
+
+    % git push --follow-tags -u origin master upstream-dfsg
+
+=back
+
+=head2 DFSG-non-free: When upstream releases only tarballs
 
 The easiest way to handle this is to add a B<Files-Excluded> field to
 I<debian/copyright>, and a B<uversionmangle> setting in
@@ -478,6 +507,10 @@ If that fails, because your branch and the NMUers work represent
 divergent branches of development, you have a number of options.  Here
 we describe the two simplest.
 
+Note that you should not try to resolve the divergent branches by
+editing files in I<debian/patches>.  Changes there would either cause
+trouble, or be overwritten by git-debrebase(1).
+
 =head2 Rebasing your work onto the NMU
 
 =over 4
@@ -490,8 +523,8 @@ If the NMUer added new commits modifying the upstream source, you will
 probably want to debrebase before your next upload to tidy those up.
 
 For example, the NMUer might have used git-revert(1) to unapply one of
-your patches.  A debrebase will strip both the patch and the reversion
-from the delta queue.
+your patches.  A debrebase can be used to strip both the patch and the
+reversion from the delta queue.
 
 =head2 Manually applying the debdiff
 
@@ -507,27 +540,49 @@ I<--overwrite>.
 Above we noted that each time you conclude a debrebase, you introduce
 a pseudomerge into your git history, which may make it harder to read.
 
-A convention you can use to minimise the number of pseudomerges is to
-debrebase only right before you upload.
+A simple convention you can use to minimise the number of pseudomerges
+is to B<git debrebase conclude> only right before you upload or push
+to B<salsa.debian.org>.
+
+It is possible, though much less convenient, to reduce the number of
+pseudomerges yet further.  We debrebase only (i) when importing a new
+release, and (ii) right before uploading.  Instead of editing the
+existing delta queue, you append fixup commits (and reversions of
+commits) that alter the upstream source to the required state.  You
+can push and pull to and from B<salsa.debian.org> during this.  Just
+before uploading, you debrebase, once, to tidy everything up.
 
-Before that point, instead of editing the existing delta queue, you
-append fixup commits (and reversions of commits) that alter the
-upstream source to the required state.  You can freely push and pull
-from B<salsa.debian.org> during this.  Just before uploading, you
-debrebase, once, to tidy everything up.
+=head2 The debian/patches directory
+
+In this workflow, I<debian/patches> is purely an output of
+git-debrebase(1).  You should not make changes there.  They will
+either cause trouble, or be ignored and overwritten by
+git-debrebase(1).
+
+I<debian/patches> will often be out-of-date because git-debrebase(1)
+will only regenerate it when it needs to.  So you should not rely on
+the information in that directory.  When preparing patches to forward
+upstream, you should use git-format-patch(1) on git commits, rather
+than sending files from I<debian/patches>.
 
 =head2 Upstream branches
 
-Except in the case where upstream releases only tarballs, we do not
-maintain a separate 'upstream' branch (unless you also happen to be
-involved in upstream development).  We work with upstream tags rather
-than any branches, except temporary branches used to prepare patches
-for forwarding upstream, for example.
+In this workflow, we specify upstream tags rather than any branches.
+
+Except when (i) upstream releases only tarballs, (ii) we require DFSG
+filtering, or (iii) you also happen to be involved in upstream
+development, we do not maintain any local branch corresponding to
+upstream, except temporary branches used to prepare patches for
+forwarding, and the like.
 
-The thought behind this is that branches are things to which one
-expects to commit, while tags are immutable points in history.  From
-the Debian point of the view, the upstream source is immutable.  It's
-our packaging to which we expect to commit.
+The idea here is that from Debian's point of view, upstream releases
+are immutable points in history.  We want to make sure that we are
+basing our Debian package on a properly identified upstream version,
+rather than some arbitrary commit on some branch.  Tags are more
+useful for this.
+
+Upstream's branches remain available as the git remote tracking
+branches for your upstream remote, e.g. I<remotes/upstream/master>.
 
 =head2 The first ever dgit push
 
@@ -540,11 +595,11 @@ package, but this should already be represented in your git history.)
 =head2 Alternative ways to start a debrebase
 
 Above we started an interactive debrebase by invoking git-debrebase(1)
-without any arguments, i.e.
+like this:
 
 =over 4
 
-    % git debrebase
+    % git debrebase -i
 
 =back
 
@@ -569,11 +624,11 @@ using git-rebase(1) directly.  For example,
 =back
 
 If you take this approach, you should be very careful not to start the
-rebase earlier than the beginning of the delta queue.
+rebase too early.
 
 =head1 SEE ALSO
 
-dgit(1), dgit(7)
+dgit(1), dgit(7), git-debrebase(1), git-debrebase(5)
 
 =head1 AUTHOR