talk.txt

   1 ===== title slide
   2
   3 Hi.
   4
   5 ===== context slide
   6
   7 Sean Whitton and I are here to present a new git workflow tool for
   8 Debian packaging.  It's primarily intended for Debian package
   9 maintainers.  It's an alternative to gbp pq and to git-dpm.
  10
  11 Before I get tell you all about it I need to show where it fits into
  12 the ecosystem of Debian package management software.  On this slide we
  13 have you, the maintainer, on the left.  On the right we have the
  14 Debian repositories.
  15
  16 You may have heard me plugging dgit once or twice.  You should all use
  17 dgit!  dgit push publishes your git history so Debian's users can use
  18 it!  But, that's not actually what I am here to talk about today.
  19 git-debrebase does not need dgit, and dgit does not need
  20 git-debrebase.
  21
  22 git-debrebase is a tool to help manage your git branch containing the
  23 Debian version of a package you maintain.  git-debrebase helps you
  24 maintain a useful git branch with the contents you need (for building
  25 and uploading).
  26
  27 It maintains your Debian delta queue - that is, that is, the changes
  28 you make, for Debian, to the upstream parts of the package - as a
  29 series of commits.
  30
  31 ===== usp slide 1
  32
  33 git-debrebase offers a standard git-rebase workflow, where you edit
  34 the whole package all together.  The experience is very like using
  35 plain git-rebase to edit a topic branch.  Delta queue editing can be
  36 done at any time, interleaved with packaging work.
  37
  38 As you make new commits, you may make commits to upstream files, and
  39 commits to packaging, in any order.  So you can just git-cherry-pick
  40 from upstream.  You can make fixup commits, and use the git-rebase
  41 autosquash syntax to have them automatically folded in by the next
  42 rebase.  If you wish, you may make "mixed" commits containing both
  43 changes to upstream files and changes to packaging files.
  44
  45 As far as I know there are no other tools that offer these features.
  46 Both gbp pq and git-dpm require you to switch to a separate view in
  47 order to edit the delta queue.  Some tools have specific functions for
  48 cherry-pick, but with none of them you can just cherry pick or git-am
  49 onto your current HEAD.
  50
  51 Of course you can always directly edit the source if you use a plain
  52 git merge workflow and non-quilt source package - for example, as
  53 described in the dgit-maint-merge tutorial manpage.  But of course
  54 that does not maintain the Debian delta as a broken-down series.
  55
  56 Also, unlike git-dpm and some other tools, git-debrebase has no
  57 in-tree metadata, so it can't get out of date or be desynchronised.
  58
  59 ===== usp slide 2
  60
  61 Unlike with gbp pq and git-dpm, there is no need to ever switch
  62 branches.  git-debrebase only uses one branch to handle all for your
  63 Debian work.  (Usually you will have an upstream branch as well of
  64 course, and if you are working in multiple Debian releases, backports
  65 for example, you will have branches for those.)
  66
  67 Yowr working tree is always immediately buildable with
  68 dpkg-buildpackage.  And it is never made dirty by git-debrebase or any
  69 of the other tooling.  Because your working tree always has the delta
  70 queue applied, it is never dirtied by patch application.  Because
  71 there is no metadata, you can never get a metadata conflict.
  72
  73 Because git-debrebase treats the quilt patches in debian/patches/ as
  74 an output, and handles them entirely automatically, your tree is never
  75 dirtied by the generation of patches.  And you never need to read any
  76 diffs of diffs.
  77
  78 ===== usp slide 3
  79
  80 And, my last slide of non-bugs:
  81
  82 git-blame, and git-log on a file, work entirely properly.  For
  83 example, if you do git-log on a file from upstream which was changed
  84 in the Debian delta queue, git-log will show the Debian delta queue
  85 commits, preceded by the upstream history.
  86
  87 If you run git-blame you will see a correct indication of which
  88 upstream and/or delta queue commits introduced each line.  Or, for a
  89 file in the debian directory, you will see a correct reporting of
  90 which commits in the package's packaging history introduced each line.
  91
  92 With git-debrebase, you never need to use the quilt program.  You can
  93 mostly ignore the 3.0 quilt source format.  (Unfortunately you will
  94 still get trouble if you make changes in git which 3.0 quilt cannot
  95 represent).
  96
  97 When you use git-debrebase with 3.0 quilt, the quilt output is always
  98 perfect and pretty, just as other people consuming .dscs have come to
  99 expect.
 100
 101 And finally: of course, git-debrebase is compatible with dgit.  You do
 102 not need to pass any quilt mode option.  And, you always can upload
 103 right away.  All necessary bureaucracy is done automatically by dgit
 104 push-source.
 105
 106 ===== demo
 107
 108 ===== data model slide up to "2" [1]
 109
 110 Now you've seen it in action, I'm going to quickly run through the
 111 data model.
 112
 113 This slide shows a likely situation, which you might find in the
 114 middle of an editing session.
 115
 116 The horizontal part near the bottom is called the Breakwater.  This
 117 branch contains unpatched upstream source code, plus the Debian
 118 packaging in the debian directory.  It does not contain any
 119 representation of the delta queue.  So it does not contain
 120 debian/patches.  In the example, commits A and B are packaging work.
 121
 122 On top of that, in this example there are two Debian delta queue
 123 commits, 1 and 2.  These are commits touching upstream files.  You
 124 current master is at 2.  So your tree contains the patched source
 125 code plus the packaging.
 126
 127 Suppose you make a change like the one Sean made in the demo:
 128
 129 ===== data model slide up to "D3" [2]
 130
 131 I'm calling this C3.  That's a commit which edits an upstream file and
 132 also debian/changelog.  After that, your tree is, of course, still
 133 fine: you can build and test it right away.
 134
 135 But suppose you want to tidy things up, and, in particular, that you
 136 wanted the new upstream change to actually come before 2.  You use
 137 git-debrebase -i.  The usual git-rebase todo list comes up, and you
 138 will see in it what looks like commit C3, and reorder that.  Assuming
 139 there are no conflicts, the result looks like this:
 140
 141 ===== data model slide up to "2'" [3]
 142
 143 You see that D3 has been split into two commits: C', which contains
 144 the changelog change, and 3' which contains the upstream change.  The
 145 upstream change is now in the delta queue in the proper place.
 146
 147 What about a new upstream version ?
 148
 149 ===== data model slide up to "2''" [4]
 150
 151 You run git-debrebase new-upstream.  It makes a special merge which
 152 folds the new upstream source code, unchanged, into your breakwater
 153 branch.  It also updates the changelog for you.  That is the new
 154 breakwater.  It then rebases the delta queue commits onto the new
 155 breakwater.
 156
 157 ===== data model slide up to PM [5]
 158
 159 Finally, let's consider an upload.  The upload has to be fast forward
 160 from the previous version of the package.
 161
 162 So git-debrebase will make a pseudomerge.
 163
 164 ===== data model zoom in on pseudomerge and add patches 4b
 165
 166 A pseudomerge is a merge commit which takes its contents from only one
 167 of its parents.  You would make one by hand with git-merge -s ours,
 168 if you wanted to make your HEAD fast forward, and know that all the
 169 wanted changes from the other branch are included.
 170
 171 git-debrebase records the previous branch state, so that it can make
 172 the right pseudomerge.  Your new branch is derived from the previous
 173 one, so it is right to declare that it is fast forward, too.
 174
 175 The branch with the pseudomerge is suitable for pushing to any git
 176 server.  It's what you would push to salsa, say.
 177
 178 Also, when you upload a 3.0 quilt package, the contents of
 179 debian/patches need to be right.  That is taken care of automatically:
 180 a commit is made adding the delta queue to debian/patches.
 181
 182 ===== data model slide up to PM [5] AGAIN
 183
 184 Next time you stark work, using git-debrebase, both the pseudomerge
 185 and the patch addition will be stripped, so that you once again have a
 186 nice delta queue to edit.
 187
 188 That'll put you back in a situation like I introduced at the start.
 189
 190 ===== data model slide merge conflict failure
 191
 192 What if you have a merge conflict during the upstream rebase ?
 193
 194 git-rebase users will have seen this kind of situation before.
 195 git-rebase stops at the first commit which can't be applied in
 196 the new context, and asks the user for help.
 197
 198 This looks quite bad.  Of course, it's not good.  But, this is an
 199 irreducible aspect of maintaining a delta queue on top of a moving
 200 target.  Sometimes, you'll need to fix up conflicts.
 201
 202 At least with git-rebase, you at least get good tools to help you fix
 203 it up.  Some of the other workflows can involve trying to resolve
 204 merge conflicts during quilt apply.  Much less fun.
 205
 206 Also, git-debrebase new-upstream is quite low commitment.  Imagine,
 207 like on the diagram here, git-rebase has applied commit 1, and stopped
 208 because it can't apply commit 3'.
 209
 210 Now, if you decide that this is too difficult to deal with today, you
 211 can just say git rebase --abort and everything just gets put back.
 212
 213 ===== data model slide merge conflict failure, new stuff greyed out
 214
 215 The autogenerated special breakwater merge, and changelog entry, are
 216 discarded, leaving you just where you were before.  You've wasted no
 217 effort because everything you're throwing away was machine-made.
 218