upload right away. All necessary bureaucracy is done automatically by
dgit push-source.
+OK, that concludes the marketing spiel. Now we're going to have a
+quick demo. Sean ?
+
===== 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.
+data model and history structure.
+
+There are some important detail 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.
-This slide shows a likely situation, which you might find in the
+So. 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.
+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.
+
+In the example, commits A and B are packaging work.
+
+The Debian delta queue sits on top of that. In this example there are
+two Debian delta queue commits, 1 and 2. These are commits touching
+upstream files. In the diagram your current HEAD (ie, your local
+master branch) is at 2. So your tree contains the patched source code
+plus the packaging: ie, it is your actual, patched, source package.
-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.
+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).
-Suppose you make a change like the one Sean made in the demo:
+OK then, 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.
+I'm calling this C3. The reason for this name will be clear in a
+moment.
+
+Sean's commit edited an upstream file and also debian/changelog. So
+if you do 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:
+wanted the new upstream change to actually come before 2. Maybe it
+just makes more sense there, or maybe you are going to change patch 3
+to make use of it.
+
+===== 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:
===== 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.
+You can see that C3 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.
+
+C', the packaging part of your new commit, has been pushed down to the
+bottom of the stack and become part of the breakwater.
+
+This is the general scheme of things: we have a fast-forwarding
+breakwater containing packaging and unchanged upstream files. It
+doesn't have a ref to itself; instead, it is contained within your
+master branch. Each time you git-debrebase, the rebase starts on the
+breakwater.
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.
+To rebase onto a new upstream version, you run git-debrebase
+new-upstream. git-debrebase expects the upstream code in the form of
+a git commit, of course. (Actually, by default, it hopes to find a
+tag named after the new upstream version number, but you can tell it
+explicitly if that's not right.)
+
+git-debrebase arranges to include the new upstream source into the
+breakwater, and then rebases your delta queue series onto that.
+
+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.
+
+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.
+
+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. There are tools
+like git-deborig to help with that.
===== 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, indeed, let's consider an upload to Debian. (And let's imagine
+you made or obtained a suitable orig tarball.)
-So git-debrebase will make a pseudomerge.
+There's a certain amount of bureaucracy to be done. In the usual case
+of an upload with dgit, this is all done for you automatically, so you
+don't really need to worry about it.
-===== data model zoom in on pseudomerge and add patches 4b
+But it's useful to understand what's going on, so I'm going to explain
+it.
+
+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
+achieve this, git-debrebase will make a pseudomerge.
+
+===== data model zoom in on pseudomerge
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,
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 zoom in on pseudomerge and add patches 4b
+
+Secondly, when you upload a 3.0 quilt package, the contents of
+debian/patches need to be right. Again, that is taken care of
+automatically: a commit is made adding a patch representation of the
+delta queue to debian/patches.
+
+You can safely ignore these autogenerated commits
===== data model slide up to PM [5] AGAIN
+And indeed, they will be stripped out:
+
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 up to PM [5]
+
+After uploading you'll want to push your branch to salsa, if you have
+a team repository there. That makes sure all the views of your
+package are up to date, so that other members of your team won't
+accidentally base their work on an old version.
+
+You can just push a git-debrebase branch which has had the pseudomerge
+made, called a `stitched' branch, with git push. It's a normal fast
+forwarding git branch.
+
+If you want to push without uploading that's fine too: git-debrebase
+stitch will just make the pseudomerge for you, giving you a
+fast-forwarding branch suitable for pushing to salsa or whereever.
+
+There is one caveat I should mention: right now, if two git-debrebase
+branches diverge, it is not trivial to merge them again. If
+git-debrebase encounters a normal `git merge' it will stop and fail.
+I have ideas about how to do better at this, but it's not a trivial
+problem. gbp pq handles this kind of situation by asking you to merge
+the actual patches: ie, you can end up resolving merge conflicts in
+diffs. Most of the other tools handle this badly too. Watch this
+space. But, for now, avoid allowing your git-debrebase branch to
+diverge. git-debrebase will help you with that by often spotting when
+it is about to occur.
+
===== data model slide merge conflict failure
What if you have a merge conflict during the upstream rebase ?
~ijackson / talk-2018-dc18-gdr.git / commitdiff