README.git-debrebase

   1
   2
   3 My preferred answer is that it is a constantly rebasing branch topped
   4 with a series of pseudomerges to make it fast-forwarding.
   5
   6            ------/--A!----/--B3!--%--/--> interchange view
   7                 /        /          /      with debian/ directory
   8                %        %          %       all upstream changes applied
   9               /        /          /        3.0 (quilt) has debian/patches
  10              /        /          3*
  11             /        /          /
  12            2*       2*         2
  13           /        /          /
  14          1        1          1    `breakwater' branch, merging baseline
  15         /        /          /     unmodified upstream code
  16     ---@-----@--A----@--B--C      plus debian/ (but no debian/patches)
  17       /     /       /                     no ref refers to this: we
  18    --#-----#-------#-----> upstream        reconstruct its identity by
  19                                            inspecting interchange branch
  20     Key:
  21
  22       1,2,3   commits touching upstream files only
  23       A,B,C   commits touching debian/ only
  24       B3      mixed commit (eg made by an NMUer)
  25       #       upstream releases
  26
  27      -@-      anchor merge, takes contents of debian/ from the
  28      /         previous `breakwater' commit and rest from upstream
  29
  30      -/-      pseudomerge; contents are identical to
  31      /         parent lower on diagram.
  32
  33       %       dgit-generated commit of debian/patches.
  34               `3.0 (quilt)' only; dropped by rebase tool.
  35
  36       *       Maintainer's HEAD was here while they were editing,
  37               before they said they were done, at which point their
  38               tools generated [% and] -/- commit[s] to convert to
  39               the fast-forwarding interchange branch.  (Maybe the
  40               tooling is simply `dgit push'.)
  41
  42       !       NMUer's HEAD was here when they said `dgit push'.
  43               Rebase branch launderer turns each ! into an
  44               equivalent *.
  45
  46
  47 Looking from the tip of the interchange view, it is I think always
  48 possible to classify these commits appropriately: pseudomerges are
  49 fairly obvious (if all three trees are identical, we descend to the
  50 parent with the most recent commit date).  The `@' special merge is
  51 the only non-pseudo merge and has a special form; also, it will be
  52 generated only by our tools so can have an annotation in the commit
  53 message.
  54
  55 So it would be possible to write a `git-debrebase' tool which would
  56 take (for example) B4, above, and be able to perform functions like:
  57
  58  * Strip pseudomerges: Rewrite the current branch so it contains no
  59    pseudomerges, turning ...B3 into ...@-A-1-2-B3.  (This should
  60    make a note, in your .git/ somewhere, of the original branch
  61    tip so that it can be overwritten with a pseudomerge.)
  62
  63  * Cleanup branch: Reorganise the current branch so that the debian/
  64    changes come first, turning -@-A-1-2-B3 into ...@-A-B-1-2-3.
  65
  66  * New upstream rebase: Start rebasing onto a new upstream version,
  67    turning ...#..@-A-B-1-2-3 into (...#..@-A-B-|...#'-)@'-1-2.  This
  68    would be a wrapper around git-rebase, which prepares @' and then
  69    tries to rebase 1 2 onto @'.  So if you ask for an interactive
  70    rebase @' doesn't appear in your commit list.
  71
  72    Note that the construction of @' cannot fail because @' simply
  73    copies debian/ from B and and everything else from #'.  (Rebasing A
  74    and B is undesirable.  We want the debian/ files to be non-rebasing
  75    so we can `git log' and get the packaging history.)
  76
  77  * Record pseudomerge.  This is like "committing" your patch queue.
  78    The LH parent is taken from the previously recorded tip.  (We could
  79    perhaps check that this is consistent with what we see in
  80    debian/changelog, but that is not a sufficient check so the
  81    recorded tip check is primary.)
  82
  83 Maybe some of these operations should automatically edit
  84 debian/changelog.
  85
  86 Nonlinear (merging) history in the interchange branch is awkward
  87 because it (obviously) does not preserve the patch queue.
  88
  89 Nonlinear (merging) history in the `packaging-only' branch is OK, if
  90 we could generate it.  We will use the commit message annotation to
  91 distinguish a merge of two `packaging-only' branches from the special
  92 merge `@'.  (Indeed I since upstream might copy debian/ from us,
  93 without the annotation and knowledge of the construction order it is
  94 not easy to reliably distinguish the two parents of a `@'.  In the
  95 most exciting edge case, upstream might `git merge' a previous
  96 instance of our interchange view, but I think even then everything
  97 still works.)
  98
  99 Sean Whitton writes ("Re: Feedback on 3.0 source format problems"):
 100 >  Does the [breakwater] branch contain debian/ alone?
 101
 102 No, it also contains a complete unmodified copy of the upstream code.
 103 (Except that if upstream had a debian/ directory, it is completely
 104 replaced.)
 105
 106 For `3.0 (quilt)' the breakwater branch contains roughly what you
 107 would get if you untarred the origs and the debian.tar.gz, and then
 108 deleted all the patches without applying them.
 109
 110
 111 dgit import handling
 112 --------------------
 113
 114 Consider a non-dgit NMU followed by a dgit NMU:
 115
 116
 117
 118             interchange --/--B3!--%--/----D*-->
 119                          /          /
 120                         %          4
 121                        /          3
 122                       /          2
 123                      /          1
 124                     2*         &_
 125                    /          /| \
 126                   1          0 00 =XBC%
 127                  /
 128                 /
 129           --@--A     breakwater
 130            /
 131         --#--------> upstream
 132
 133
 134  Key:
 135
 136     =XBC%     dgit tarball import of .debian.tar.gz containing
 137               Debian packaging including changes B C and patches
 138
 139     0         dgit tarball import of upstream tarball
 140     00        dgit tarball import of supplementary upstream tarball
 141     &_        dgit nearly-breakwater import
 142     &'        git-debrebase converted import (upstream files only)
 143     D'        git-debrebase converted debian/ changes import
 144
 145     * **      before and after HEAD
 146
 147 Want to transform this into:
 148
 149  I. No new upstream version (0 + 00 eq #)
 150
 151                         --/--B3!--%--/------D*-------------/-->
 152                          /          /                     /
 153                         %          4                     4**
 154                        /          3                     3
 155                       /          2                     2
 156                      /          1                     1
 157                     2*         &_                    /
 158                    /          /| \                  /
 159                   1          0 00 =XBC%            /
 160                  /                                /
 161                 /                                /
 162           --@--A-----B-----------------------C--D
 163            /
 164         --#----------------------------------------->
 165
 166
 167  II. New upstream (0 + 00 neq #)
 168
 169                         --/--B3!--%--/------D*-------------/-->
 170                          /          /                     /
 171                         %          4                     4**
 172                        /          3                     3
 173                       /          2                     2
 174                      /          1                     1
 175                     2*         &_                    /
 176                    /          /| \                  /
 177                   1          0 00 =XBC%            /
 178                  /                                /
 179                 /                                /
 180           --@--A-----B--------------------@--C--D
 181            /                             /
 182         --#----------------------- - -  /  - - ----->
 183                                        /
 184                                       &'
 185                                      /|
 186                                     0 00