README.git-debrebase

   1 From: Ian Jackson <ijackson@chiark.greenend.org.uk>
   2 To: Russ Allbery <rra@debian.org>
   3 Cc: debian-devel@lists.debian.org
   4 Subject: Re: Feedback on 3.0 source format problems
   5 Date: Wed, 4 Jan 2017 12:08:57 +0000
   6
   7 Russ Allbery writes ("Re: Feedback on 3.0 source format problems"):
   8 > Even if we never used tarballs, and instead our unit of operation was the
   9 > upstream Git repository plus Debian branches, I would maintain a rebased
  10 > branch of Debian changes to upstream
  11
  12 I think this is definitely the right thing for many packages.
  13
  14 I don't think this depends on the interchange format representing the
  15 changes as patches rather than commits.  At a technical level, they
  16 represent roughly the same information and it is possible to
  17 interconvert.  However:
  18
  19   * There are many changes that patches cannot represent.
  20
  21   * git (working with a rebasing branch) is a much more powerful tool
  22     for editing a patch series than quilt or diff/patch or emacs
  23     (working with a series of patches as files).  Ie, patches are a
  24     poor editing format.  Consequently most people actually gateway to
  25     git at the first opportunity, and out again for export.
  26
  27   * Few people outside Debian work with quilt stacks any more.
  28
  29 All of these things mean that patches are a really poor interchange
  30 format.
  31
  32 The only difficulty is this one:
  33
  34 > This is actually, in a way, *harder* if we were using pure Git, since if I
  35 > have a rebased branch of Debian changes on top of upstream, and I need a
  36 > place to integrate that with Debian packaging, what does that
  37 > debian/master branch look like?  I don't really want it to be a constantly
  38 > rebased branch; I want it to be a conventional branch.  But I want to keep
  39 > merging the changes against upstream into it (but not maintain them on
  40 > that branch, only maintain the Debian packaging files on that branch).
  41
  42 My preferred answer is that it is a constantly rebasing branch topped
  43 with a series of pseudomerges to make it fast-forwarding.
  44
  45 git-dpm sort of does this.  I have been experimenting with and
  46 blundering towards another approach, which is closer to raw git.
  47
  48 Something like this:
  49
  50          ------/--A-----/---B3---/--> interchange view
  51               /        /        /
  52              /        /        3
  53             /        /        /
  54            2        2        2
  55           /        /        /
  56          1        1        1
  57         /        /        /
  58     ---p-----p--A----p---B---> `packaging-only' branch
  59       /     /       /
  60    --#-----#-------#-----> upstream
  61
  62     Key:       1,2,3   commits touching upstream files
  63                A,B     commits touching debian/ only
  64                B3      mixed commit (eg made by an NMUer)
  65                #       upstream releases
  66
  67               -p-      special merge, takes contents of debian/
  68               /          from the previous `packaging only'
  69                          commit and rest from upstream
  70
  71               -/-      pseudomerge; contents are identical to
  72               /         parent lower on diagram.
  73
  74 Looking from the tip of the interchange view, it is I think always
  75 possible to classify these commits appropriately: pseudomerges are
  76 fairly obvious (if all three trees are identical, we descend to the
  77 parent with the most recent commit date), and the `p' special merge is
  78 the only non-pseudo merge and has a special form.
  79
  80 So it would be possible to write a `git-debian-rebase' tool which
  81 would take (for example) B3, above, and be able to perform functions
  82 like:
  83
  84  * Strip pseudomerges: Rewrite the current branch so it contains no
  85    pseudomerges, turning ...B3 into ...p-A-1-2-B3.  (This should make
  86    a note, in your .git/ somewhere, of the latest pseudomerge to be
  87    deleted.)
  88
  89  * Cleanup branch: Reorganise the current branch so that the debian/
  90    changes come first, turning -p-A-1-2-B3 into ...p-A-B-1-2.
  91
  92  * New upstream rebase: Start rebasing onto a new upstream version,
  93    turning ...#...p-A-B-1-2 into ...#'...p'-1-2.  This would be a
  94    wrapper around git-rebase, which prepares p' and then tries to
  95    rebase 1 2 onto p'.  So if you ask for an interactive rebase p'
  96    doesn't appear in your commit list.
  97
  98    Note that the rebasing of p into p' cannot fail because p' simply
  99    copies debian/ from B and and everything else from #'.  (Rebasing A
 100    and B is undesirable.  We want the debian/ files to be non-rebasing
 101    so we can `git log' and get the packaging history.)
 102
 103  * Record pseudomerge.  This is like "committing" your patch queue.
 104    The LH parent is taken from the previous strip pseudomerge.  (We
 105    should probably check that this is consistent with what we see in
 106    debian/changelog, but that is not a sufficient check.)
 107
 108 Maybe some of these operations should automatically edit
 109 debian/changelog.
 110
 111 The only thing that this can't easily do is permit nonlinear (ie,
 112 merging) history on the `packaging-only' branch, because upstream
 113 might contain debian/ files too, so it is not possible to distinguish
 114 a merge of two `packaging-only' branches from the special merge `p'.
 115 (Indeed I since upstream might copy debian/ from us, I think it is not
 116 easy to reliably distinguish the two parents of a `p'.  In the most
 117 exciting edge case, upstream might `git merge' a previous instance of
 118 our interchange view, but I think even then everything still works.)
 119
 120 Ian.
 121
 122 --
 123 Ian Jackson <ijackson@chiark.greenend.org.uk>   These opinions are my own.
 124
 125 If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
 126 a private address which bypasses my fierce spamfilter.
 127
 128 From: Ian Jackson <ijackson@chiark.greenend.org.uk>
 129 To: Sean Whitton <spwhitton@spwhitton.name>
 130 Cc: debian-devel@lists.debian.org
 131 Subject: Re: Feedback on 3.0 source format problems
 132 Date: Fri, 6 Jan 2017 15:29:38 +0000
 133
 134 Sean Whitton writes ("Re: Feedback on 3.0 source format problems"):
 135 > Could you explain in general terms the difference between the
 136 > interchange and packaging-only branches
 137
 138 See modified diagram below.  Are the annotations I have added (and the
 139 name change) any help ?
 140
 141 >  Does the packaging-only branch contain debian/ alone?
 142
 143 No, it also contains a complete unmodified copy of the upstream code.
 144 (Except that if upstream had a debian/ directory, it is completely
 145 replaced.)  Perhaps this is the wrong name.  Let's try
 146 `merging-baseline'
 147
 148 For `3.0 (quilt)' the merging-baseline branch contains roughly what
 149 you would get if you untarred the origs and the debian.tar.gz, and
 150 then deleted all the patches without applying them.
 151
 152 Not shown on the diagram is the commit `add patch queue to
 153 debian/patches', which would be needed for `3.0 (quilt)'.  This is
 154 because the diagram is in terms of a sane source format, not `3.0
 155 (quilt)'.  For use with quilty sources, there would be such a commit
 156 (probably dgit-generated) on top of the actual upstream change
 157 commits:
 158
 159            ------/--A!----/--B3!--%--/--> interchange view
 160                 /        /          /      with debian/ directory
 161                %        %          %       all upstream changes applied
 162               /        /          /        3.0 (quilt) has debian/patches
 163              /        2*         2*
 164             /        /          /
 165            2*       2          2
 166           /        /          /
 167          1        1          1    `merging-baseline' branch
 168         /        /          /     unmodified upstream code
 169     ---p-----p--A----p--B--C-->   plus debian/ (but no debian/patches)
 170       /     /       /
 171    --#-----#-------#-----> upstream
 172
 173     Key:
 174
 175       1,2,3   commits touching upstream files only
 176       A,B,C   commits touching debian/ only
 177       B3      mixed commit (eg made by an NMUer)
 178       #       upstream releases
 179
 180      -p-      special merge, takes contents of debian/ from the
 181      /         previous `merging-baseline' commit and rest from upstream
 182
 183      -/-      pseudomerge; contents are identical to
 184      /         parent lower on diagram.
 185
 186       %       dgit-generated commit of debian/patches.
 187               `3.0 (quilt)' only; dropped by rebase tool.
 188
 189       *       Maintainer's HEAD was here while they were editing,
 190               before they said they were done, at which point their
 191               tools generated [% and] -/- commit[s] to convert to
 192               the fast-forwarding interchange branch.  (Maybe the
 193               tooling is simply `dgit push'.)
 194
 195       !       NMUer's HEAD was here when they said `dgit push'.
 196               Rebase branch launderer turns each ! into an
 197               equivalent *.
 198
 199 Ian.
 200
 201 --
 202 Ian Jackson <ijackson@chiark.greenend.org.uk>   These opinions are my own.
 203
 204 If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
 205 a private address which bypasses my fierce spamfilter.