chiark / gitweb /
dgit-maint-debrebase(7): make the wood visible despite the trees
authorSean Whitton <spwhitton@spwhitton.name>
Tue, 3 Apr 2018 18:31:45 +0000 (11:31 -0700)
committerSean Whitton <spwhitton@spwhitton.name>
Thu, 19 Apr 2018 16:43:51 +0000 (09:43 -0700)
Signed-off-by: Sean Whitton <spwhitton@spwhitton.name>
dgit-maint-debrebase.7.pod

index cd470ce..bdfdc8b 100644 (file)
@@ -54,10 +54,9 @@ maintain Debian source packages which use that format.
 This workflow is appropriate for packages where the Debian delta
 contains multiple pieces which interact, or which you don't expect to
 be able to upstream soon.  For packages with simple and/or short-lived
-Debian deltas, use of git-debrebase(1) might introduce unneeded
-complexity -- for example, you cannot use B<git merge> to incorporate
-changes from other contributors.  For such packages, consider the
-workflow described in dgit-maint-merge(7).
+Debian deltas, use of git-debrebase(1) introduces unneeded complexity.
+For such packages, consider the workflow described in
+dgit-maint-merge(7).
 
 =head1 INITIAL DEBIANISATION
 
@@ -94,12 +93,8 @@ something like this:
 =back
 
 Now go ahead and Debianise your package.  Just make commits on the
-master branch, adding things in the I<debian/> directory.  If you need
-to patch the upstream source, see "EDITING THE DELTA QUEUE", below.
-Note that there is no need to 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.
+master branch, adding things in the I<debian/> directory, or patching
+the upstream source.
 
 Finally, you need an orig tarball:
 
@@ -194,7 +189,7 @@ it somewhere.  The usual choice is B<salsa.debian.org>:
 =back
 
 You are now ready to proceed as above, making commits to the
-I<debian/> directory.
+I<debian/> directory and to the upstream source.
 
 =head1 CONVERTING AN EXISTING PACKAGE
 
@@ -265,12 +260,8 @@ 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.)
+The first dgit push will require I<--overwrite>.
+
 =head1 GIT CONFIGURATION
 
 This workflow does not support using B<git merge> to merge divergent
@@ -293,6 +284,9 @@ B<branch.E<lt>nameE<gt>.rebase> settings in git-config(5).
 
 =head1 IMPORTING NEW UPSTREAM RELEASES
 
+There are two steps: obtaining git refs that correspond to the new
+release, and importing that release using git-debrebase(1).
+
 =head2 Obtaining the release
 
 =head3 When upstream tags releases in git
@@ -378,28 +372,7 @@ edit, re-order and delete patches.  Run
 =back
 
 to start an interactive rebase.  You can edit, re-order and delete
-commits just as you would during B<git rebase -i>.  Alternatively, you
-can perform a non-interactive rebase like this:
-
-=over 4
-
-    % git debrebase -- [git-rebase options...]
-
-=back
-
-A third alternative is to have git-debrebase(1) shuffle all the Debian
-changes to the end of your branch, and then manipulate them yourself
-using git-rebase(1).  For example,
-
-=over 4
-
-    % git debrebase launder
-    % git rebase -i HEAD~5      # there are 4 Debian patches
-
-=back
-
-If you take this approach, you should be very careful not to start the
-rebase earlier than the beginning of the delta queue.
+commits just as you would during B<git rebase -i>.
 
 =head2 Editing patches: finishing a debrebase
 
@@ -414,51 +387,27 @@ git remote such as B<salsa.debian.org>,
 
 =over 4
 
-    % git debrebase launder
-    % git debrebase stitch
+    % git debrebase conclude
 
 =back
 
-Note that each time you stitch 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.
-
-A strategy is to debrebase only right before you upload.  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
-to tidy everything up.
+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.
 
 =head1 BUILDING AND UPLOADING
 
-Use B<dgit build>, B<dgit sbuild>, B<dgit push> and B<dgit
-push-source> 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.
-
-After dgit pushing, be sure to git push to B<salsa.debian.org>, if
-you're using that.
+You can use dpkg-buildpackage(1) for test builds.  When you are ready
+to build for an upload, use B<dgit sbuild>.
 
-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
-HEAD has exactly the contents of the source package.  gitpkg(1) is
-highly configurable, and one dgit user reports using it to produce and
-test multiple source packages, from different branches corresponding
-to each of the current Debian suites.
+Upload with B<dgit push> or B<dgit push-source>.  Remember to pass
+I<--new> if the package is new in the target suite.
 
-If you want to skip dgit's checks while iterating on a problem with
-the package build (for example, you don't want to commit your changes
-to git), you can just run dpkg-buildpackage(1) or debuild(1) instead.
-
-=head2 Laundering the delta queue before uploading
-
-Just before you B<dgit push> or B<dgit push-source>, you might want to
-have git-debrebase(1) shuffle your branch such that the Debian delta
-queue appears at the end:
+Right before uploading, if you did not just already do so, you might
+want to have git-debrebase(1) shuffle your branch such that the Debian
+delta queue appears right at the tip of the branch you will push:
 
 =over 4
 
@@ -469,6 +418,9 @@ queue appears at the end:
 
 Note that this will introduce a new pseudomerge.
 
+After dgit pushing, be sure to git push to B<salsa.debian.org>, if
+you're using that.
+
 =head1 HANDLING DFSG-NON-FREE MATERIAL
 
 This covers only DFSG-non-free material.  Material which is legally
@@ -540,6 +492,77 @@ B<salsa.debian.org>, say, you can manually apply the NMU debdiff,
 commit and debrebase.  The next B<dgit push> will require
 I<--overwrite>.
 
+=head1 HINTS AND TIPS
+
+=head2 Minimising pseudomerges
+
+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.
+
+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 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.
+
+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.
+
+=head2 The first ever dgit push
+
+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.)
+
+=head2 Alternative ways to start a debrebase
+
+Above we started an interactive debrebase by invoking git-debrebase(1)
+without any arguments, i.e.
+
+=over 4
+
+    % git debrebase
+
+=back
+
+It is also possible to perform a non-interactive rebase, like this:
+
+=over 4
+
+    % git debrebase -- [git-rebase options...]
+
+=back
+
+
+A third alternative is to have git-debrebase(1) shuffle all the Debian
+changes to the end of your branch, and then manipulate them yourself
+using git-rebase(1) directly.  For example,
+
+=over 4
+
+    % git debrebase launder
+    % git rebase -i HEAD~5      # there are 4 Debian patches
+
+=back
+
+If you take this approach, you should be very careful not to start the
+rebase earlier than the beginning of the delta queue.
+
 =head1 SEE ALSO
 
 dgit(1), dgit(7)