-[title slide]
+===== title slide
Hi.
-[context slide]
+===== context slide
Sean Whitton and I are here to present a new git workflow tool for
Debian packaging. It's primarily intended for Debian package
you make, for Debian, to the upstream parts of the package - as a
series of commits.
-[usp slide 1]
+===== usp slide 1
git-debrebase offers a standard git-rebase workflow, where you edit
the whole package all together. The experience is very like using
Also, unlike git-dpm and some other tools, git-debrebase has no
in-tree metadata, so it can't get out of date or be desynchronised.
-[usp slide 2]
+===== usp slide 2
Unlike with gbp pq and git-dpm, there is no need to ever switch
branches. git-debrebase only uses one branch to handle all for your
dirtied by the generation of patches. And you never need to read any
diffs of diffs.
-[usp slide 3]
+===== usp slide 3
And, my last slide of non-bugs:
right away. All necessary bureaucracy is done automatically by dgit
push-source.
+===== demo
+
+===== data model slide up to "2" [1]
+
+Now you've seen it in action, I'm going to quickly run through the
+data model.
+
+This slide shows a likely situation, which you might find in the
+middle of an editing session.
+
+The horizontal part near the bottom is called the Breakwater. This
+branch contains unpatched upstream source code, plus the Debian
+packaging in the debian directory. It does not contain any
+representation of the delta queue. So it does not contain
+debian/patches. In the example, commits A and B are packaging work.
+
+On top of that, in this example there are two Debian delta queue
+commits, 1 and 2. These are commits touching upstream files. You
+current master is at 2. So your tree contains the patched source
+code plus the packaging.
+
+Suppose you make a change like the one Sean made in the demo:
+
+===== data model slide up to "D3" [2]
+
+I'm calling this C3. That's a commit which edits an upstream file and
+also debian/changelog. After that, your tree is, of course, still
+fine: you can build and test it right away.
+
+But suppose you want to tidy things up, and, in particular, that you
+wanted the new upstream change to actually come before 2. You use
+git-debrebase -i. The usual git-rebase todo list comes up, and you
+will see in it what looks like commit C3, and reorder that. Assuming
+there are no conflicts, the result looks like this:
+
+===== data model slide up to "2'" [3]
+
+You see that D3 has been split into two commits: C', which contains
+the changelog change, and 3' which contains the upstream change. The
+upstream change is now in the delta queue in the proper place.
+
+What about a new upstream version ?
+
+===== data model slide up to "2''" [4]
+
+You run git-debrebase new-upstream. It makes a special merge which
+folds the new upstream source code, unchanged, into your breakwater
+branch. It also updates the changelog for you. That is the new
+breakwater. It then rebases the delta queue commits onto the new
+breakwater.
+
+===== data model slide up to PM [5]
+
+Finally, let's consider an upload. The upload has to be fast forward
+from the previous version of the package.
+
+So git-debrebase will make a pseudomerge.
+
+===== data model zoom in on pseudomerge and add patches 4b
+
+A pseudomerge is a merge commit which takes its contents from only one
+of its parents. You would make one by hand with git-merge -s ours,
+if you wanted to make your HEAD fast forward, and know that all the
+wanted changes from the other branch are included.
+
+git-debrebase records the previous branch state, so that it can make
+the right pseudomerge. Your new branch is derived from the previous
+one, so it is right to declare that it is fast forward, too.
+
+The branch with the pseudomerge is suitable for pushing to any git
+server. It's what you would push to salsa, say.
+
+Also, when you upload a 3.0 quilt package, the contents of
+debian/patches need to be right. That is taken care of automatically:
+a commit is made adding the delta queue to debian/patches.
+
+===== data model slide up to PM [5] AGAIN
+
+Next time you stark work, using git-debrebase, both the pseudomerge
+and the patch addition will be stripped, so that you once again have a
+nice delta queue to edit.
+
+That'll put you back in a situation like I introduced at the start.
+
+===== data model slide merge conflict failure
+
+What if you have a merge conflict during the upstream rebase ?
+
+git-rebase users will have seen this kind of situation before.
+git-rebase stops at the first commit which can't be applied in
+the new context, and asks the user for help.
+
+This looks quite bad. Of course, it's not good. But, this is an
+irreducible aspect of maintaining a delta queue on top of a moving
+target. Sometimes, you'll need to fix up conflicts.
+
+At least with git-rebase, you at least get good tools to help you fix
+it up. Some of the other workflows can involve trying to resolve
+merge conflicts during quilt apply. Much less fun.
+
+Also, git-debrebase new-upstream is quite low commitment. Imagine,
+like on the diagram here, git-rebase has applied commit 1, and stopped
+because it can't apply commit 3'.
+
+Now, if you decide that this is too difficult to deal with today, you
+can just say git rebase --abort and everything just gets put back.
+
+===== data model slide merge conflict failure, new stuff greyed out
+
+The autogenerated special breakwater merge, and changelog entry, are
+discarded, leaving you just where you were before. You've wasted no
+effort because everything you're throwing away was machine-made.
+
~ijackson / talk-2018-dc18-gdr.git / commitdiff