you don't work with patches. Instead, there is a series of commits.
So, we prefer the term "delta queue".
-It's primarily intended for Debian package maintainers, although you
-could use it outside of or alongside Debian.
+git-debrebase is primarily intended for Debian package maintainers,
+although you could use it outside of or alongside Debian.
-git-debrebase does not deal with building at all. You use whatever
-your existing build tools are.
+It does not deal with building at all. You use whatever existing
+build tools you like.
Nor does git-debrebase deal with source packages or orig tarballs. It
does not do uploads. Of course when you actually upload to Debian you
need to produce a source package. Getting a source package is, of
-course, as easy or easier than with other workflows. Usually, it is
+course, as easy, or easier than, with other workflows. Usually, it is
done automatically for you by dgit push-source, so you usually don't
need to concern yourself with .dsc source packages even when uploading
to Debian.
Of course you can share your git branch on a service like salsa,
-without building or uploading.
+without building or uploading. Then you don't need to deal with
+source packages.
===== usp slide 1
git-debrebase offers a standard git-rebase workflow, where you edit
the whole of the source code for your package, including your changes
-to upstream files and your changes to packaging, all together.
+to upstream files, and your changes to packaging, all together.
The experience is very like using plain git-rebase to edit a topic
branch. Delta queue editing can be done at any time, interleaved with
packaging work.
As far as I know there are no other tools that offer these features.
Both gbp pq and git-dpm require you to switch to a separate view in
order to edit the delta queue. Some tools have specific functions for
-cherry-pick, but with none of them you can just use plain git cherry
-pick or git-am onto your usual branch. With git-debrebase, you can
-just edit the code and commit it, with git, in the completely usual
-way.
+cherry-pick, but with none of them you can just use plain
+git-cherry-pick or git-am onto your usual branch. With git-debrebase,
+you can just edit the code and commit it, with git, in the completely
+usual way.
Specifically, at any point, you may make commits to upstream files,
-and commits to packaging, in any order. So you can just
-git-cherry-pick from upstream. You can make fixup commits, and use
-the git-rebase autosquash syntax to have them automatically folded in
-by the next rebase. If you wish, you may make "mixed" commits
-containing both changes to upstream files and changes to packaging
-files.
+and commits to packaging, in any order. So you can just cherry pick
+from upstream. You may make fixup commits, and use the git-rebase
+autosquash syntax to have them automatically folded in, by the next
+rebase. If you wish, you may make "mixed" commits containing both
+changes to upstream files and changes to packaging files.
Of course you can always directly edit the source if you use a plain
git merge workflow and non-quilt source package - for example, as
-described in the dgit-maint-merge tutorial manpage. But of course
-that does not maintain the Debian delta as a broken-down series;
-and in the source package such a merge based workflow squashes all the
-changes into a single debian-changes patch.
+described in the dgit-maint-merge tutorial manpage. But that does not
+maintain the Debian delta as a broken-down linear series of changes;
+and, in the source package, such a merge based workflow squashes all
+the changes into a single debian-changes patch.
So supporting you maintaining a delta queue - that is, a linear series
of changes - is what git-debrebase is for.
===== usp slide 2
As I said, 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
+switch branches. git-debrebase only uses one branch to handle all
your Debian work.
Of course usually you will have an upstream remote-tracking branch as
With git-debrebase, you can always immediately build binaries out of
your working tree, with dpkg-buildpackage (or whatever other build
-tool you prefer). And your working tree is never made dirty by
+tool you prefer). And, your working tree is never made dirty by
git-debrebase or any of the other tooling: Because your working tree
always has the delta queue applied, it is never dirtied by patch
application. Because there is no metadata, you can never get a
===== usp slide 3
-And, the final part of my plug:
+And, the final parts of my plug:
-With git-debrebase, git-blame, and git-log on a file, work entirely
+With git-debrebase: git-blame, and git-log on a file, work entirely
properly. For example, if you do git-log on a file from upstream
which was changed in the Debian delta queue, git-log will show the
Debian delta queue commits, preceded by the upstream history.
-We'll show an example of this in the demo.
+We'll show you an example of this in the demo.
If you run git-blame you will see a correct indication of which
upstream and/or delta queue commits introduced each line. Or, for a
With git-debrebase, you never need to use the quilt program. You can
mostly ignore the 3.0 quilt source format.
-Not having to learn much about 3.0 (quilt) is all really good for
+Not having to learn much about 3.0 quilt is really good for
newbies. Particularly, for people from other sofware development
-communities who don't know about Debian.
+communities who don't know about Debian, but usually do know git.
Unfortunately it is not possible to paper over the cracks completely:
you will still get trouble if you make changes in git which 3.0 quilt
On the other hand, when you use git-debrebase with 3.0 quilt, the
generated 3.0 quilt source package is perfect pretty, with your delta
-queue commits converted nicely into pathes - just as other people
+queue commits converted nicely into patches - just as other people
consuming .dscs have come to expect.
And finally: of course, git-debrebase is compatible with dgit. You do
not need to pass any quilt mode option to dgit. And, you always can
-upload right away. All necessary bureaucracy is done automatically by
-dgit push-source.
+upload right away. All necessary bureaucracy is done automatically
+when you say dgit push-source.
OK, that concludes the marketing spiel. Now we're going to have a
quick demo. Sean ?
Now you've seen it in action, I'm going to quickly run through the
data model and history structure.
-There are some important detail I'm going to be glossing over, so if
+There are some important details I'm going to be glossing over, so if
you actually want to know what's really going on, please read the
reference documentation in the section 5 manpage, where everything is
fully and formally defined.
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 contains neither any
-of your Debian changes to upstream files, nor any debian/patches.
+of your Debian commits changing upstream files, nor any debian/patches.
In the example, commits A and B are packaging work.
You could build it with dpkg-buildpackage -uc -b, to produce binaries
for testing. You can git grep for things and be told where they are -
-even if they are in the upstream source but in your delta queue. You
-can git log -G for things, and be told where they came from and shown
-the relevant commit (whether that's upstream, or one of yours).
+even if they are in the upstream source files but introduced by your
+delta queue. You can git log -G for things, and be told where they
+came from and shown the relevant commit (whether that's upstream, or
+one of yours).
OK then, suppose you make a change like the one Sean made in the demo:
===== data model slide with git-debrebase -i overlay
So, you run 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:
+up, and you will see in it what looks like commit C3, and reorder that
+to come before commit 2. Assuming there are no conflicts, the result
+looks like this:
===== data model slide "commit history structure after git-debrebase"
There are new commits on the breakwater: firstly, a special
merge. which folds the new upstream source code, unchanged, into your
-breakwater branch. This is called an anchor merge. The most recent
-anchor merge is the backstop for rebase processing by git-debrebase.
+breakwater branch. This is called an Anchor merge. The most recent
+Anchor merge is the backstop for rebase processing by git-debrebase.
The second commit is simply adding a new changelog entry for you.
-Having provided the new base for your delta queue, it then uses
-git-rebase --onto to rebase the delta queue commits. If you didn't
-ask for an interactive rebase, and there are no merge conflicts,
-that's it as far as the code in git is concerned.
+Having provided the new base for your delta queue, git-debrebase then
+uses git-rebase --onto to rebase the delta queue onto the new
+breakwater. If you didn't ask for an interactive rebase, and there
+are no merge conflicts, that's it. You now have the new upstream code
+with your rebased delta queue.
Of course if you are going to upload to the Debian archive you'll also
have to make an orig tarball of the new upstream. If you're using the
don't really need to worry about it.
But it's useful to understand what's going on, so I'm going to explain
-it.
+it. But, I'm going to describe it to help your understanding.
Firstly, you're going to publish your history, so your history has to
be made fast forward from the previous version of the package. To
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.
+In the example, git-debrebase had recorded 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.
+server. You could push to salsa, say.
===== data model slide "commit history structure after upload"
If you made any commits on top on top of the pseudomerge (or you
pulled any such commits from salsa, or whereever), it folds those back
-into the breakwater and the delta queue. So you once again a nice
-delta queue to edit.
+into the breakwater and the delta queue. So once again, you have a
+nice delta queue to edit.
-git-debrebase makes a note of where you were previously, so that when
-you next want to push or upload, it can stitch the history back in
-with another pseudomerge. At the start of this walkthough, that ref
-was indeed present - I glossed over that a bit.
+git-debrebase makes a note of where you were previously, so that the
+next time you want to push or upload, it can stitch the history back
+in with another pseudomerge. At the start of this walkthough, that
+ref was indeed present - I glossed over that a bit.
===== data model slide "commit history structure" again
-More common is a different kind of merge problem.
-
-What happens if you one of your delta queue commits doesn't apply
-during the upstream rebase - that is, your patch does not apply to the
-new upstream source code ?
+What happens if one of your delta queue commits doesn't apply during
+the upstream rebase - that is, your patch does not apply to the new
+upstream source code ?
===== data model slide "commit history structure failed rebase"
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.
+At least with git-debrebase, you at get good tools to help you fix it
+up. Some of the other workflows can involve trying to resolve merge
+conflicts during quilt apply, or fix up conflicts in diffs. That's
+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'.
+like on the diagram here, git-debrebase 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.
I have ideas about how to do better at this, so watch this space.
But, for now, teams should coordinate to avoid creating diverging
-git-debrebase branches. git-debrebase will help you with that by
-often spotting when it is about to occur.
+git-debrebase branches. git-debrebase will help you with that, by
+often spotting when divergence is about to occur and warning you.
===== status and references slide
+So:
+
git-debrebase is available in testing and stretch-backports and is in
good shape. Since early versions it has been battle-tested to help
with security updates to the Debian Xen packages. The documentation
features will will be added. But you can start using it right away.
The best starting point is probably the tutorial manpage
-dgit-maint-debrebase (7) (which is in the dgit package).
+dgit-maint-debrebase (which is in the dgit package).
Sean and I are holding a workshop on Tuesday morning, where anyone is
invited to come and get help with git-debrebase - and also with dgit.
-So if your questions dun't get answered before then, do drop in.
+So if your questions don't get answered before then, do drop in.
And of course I should refer to the reference documentation.
git-debrebase(5) has the data model and definition of terminology.
But, really, start with the dgit-maint-rebase tutorial, or come to the
workshop.
+
+Thank you.
+
+Questions?
~ijackson / talk-2018-dc18-gdr.git / commitdiff