NOTES.git-debrebase

   1 TODO
   2    reference docs
   3       git-debrebase(1)   command line
   4    tutorial
   5       dgit-maint-debrebase(7)
   6       someone should set branch.<name>.mergeOptions to include --ff-only ?
   7
   8    clean up remains of README
   9
  10    arrange for dgit to automatically stitch on push
  11
  12
  13
  14
  15 workflow
  16
  17   git-debrebase blah [implies start]       strips pseudomerge(s)
  18
  19   commit / git-debrebase / etc.
  20
  21   dgit --damp-run push
  22       hook: call git-debrebase prep-push   dgit push does not update remote
  23       or something, must add patches at least
  24
  25   commit / git-debrebase / etc.            strips patches
  26
  27   dgit push
  28       hook: call git-debrebase prep-push   dgit push DOES update remote
  29
  30   commit / git-debrebase / etc.            strips last pm, but arranges
  31                                            that remade pm will incorporate it
  32
  33
  34
  35 # undocumented usages:
  36 #
  37 #    git-debrebase [<options>] downstream-rebase-launder-v0  # experimental
  38
  39 # problems / outstanding questions:
  40 #
  41 #  *  dgit push with a `3.0 (quilt)' package means doing quilt
  42 #     fixup.  Usually this involves recommitting the whole patch
  43 #     series, one at a time, with dpkg-source --commit.  This is
  44 #     terribly terribly slow.  (Maybe this should be fixed in dgit.)
  45 #
  46 #  * dgit push usually needs to (re)make a pseudomerge.  The "first"
  47 #    git-debrebase stripped out the previous pseudomerge and could
  48 #    have remembeed the HEAD.  But it's not quite clear what history
  49 #    ought to be preserved and what should be discarded.  For now
  50 #    the user will have to tell dgit --overwrite.
  51 #
  52 #    To fix this, do we need a new push hook for dgit ?
  53 #
  54 #  * Workflow is currently clumsy.  Lots of spurious runes to type.
  55 #    There's not even a guide.
  56 #
  57 #  * new-upstream-v0 has a terrible UI for multiple upstream pieces.
  58 #    You end up with giant runic command lines.  Does this matter /
  59 #
  60 #    One consequence of the lack of richness it can need --force in
  61 #    fairly sensible situations and there is no way to tell it what
  62 #    you are really trying to do, other than just --force.  There
  63 #    should be an interface with some default branch names.
  64 #
  65 #  * There should be a standard convention for the version number,
  66 #    and unfinalised or not changelog, after new-upstream.
  67 #
  68 #  * Handing of multi-orig dgit new-upstream .dsc imports is known to
  69 #    be broken.  They may be not recognised, improperly converted, or
  70 #    their conversion may be unrecognised.
  71 #
  72 #  * Docs need writing and updating.  Even README.git-debrebase
  73 #    describes a design but may not reflect the implementation.
  74 #
  75 #  * We need to develop a plausible model that works for derivatives,
  76 #    who probably want to maintain their stack on top of Debian's.
  77 #    downstream-rebase-launder-v0 may be a starting point?
  78
  79
  80 ========================================
  81
  82 Theory for ffq-prev
  83
  84   refs/ffq-prev/REF    relates to refs/REF
  85
  86 When we strip a pm, we need to maybe record it (or something) as the
  87 new start point.
  88
  89 When we do a thing
  90
  91     with no recorded ffq-prev
  92
  93         ffq-prev is our current tip
  94
  95         obviously it is safe to say we will overwrite this
  96         we do check whether there are not-included changes in the remotes
  97         because if the new ffq-prev is not ff from the remotes
  98         the later pushes will fail
  99
 100         this model tends to keep ad-hoc commits made on our
 101         tip branch before we did rebase start, in the
 102         `interchange view' and also in the rebase stack.
 103
 104         also we can explicitly preserve with
 105         git-debrebase stitch
 106
 107         It is always safe to rewind ffq-prev: all
 108         that does is overwrite _less_ stuff.
 109
 110         in any case putative ffq-prev must be ff from remote.
 111         Otherwise when we push it will not be ff, even though we have
 112         made pseudomerge to overwrite ffq-prev.  So if we spot
 113         this, report an error.  see above
 114
 115     with a recorded ffq-prev
 116
 117         we may need to advance ffq-prev, to allow us to generate
 118         future pseudomerges that will be pushable
 119
 120         advancing ffq-prev is dangerous, since it might
 121         effectively cancel the commits that will-ovewrite is advanced
 122         over.
 123
 124         ??? advance it to merge-base( current remote, current tip )
 125         if possible (see above), - ie to current remote, subject
 126         to the condition that that is an ancestor of current tip
 127
 128         currently this is not implemented
 129
 130         better maybe to detect divergence ?  but it is rather late
 131         by then!
 132
 133 We check we are ff from remotes before recording new ffq-prev
 134
 135   ---------- now follows much the same info in different words ----------
 136
 137 Re git-debrebase [--noop-ok] stitch
 138
 139     we will teach dgit to do
 140        git-debrebase stitch
 141     or some such ?
 142
 143 following parts are not implemented and maybe aren't the
 144 best subcommand names etc.
 145
 146 3. git-debrebase push
 147
 148     like git push only does stitch first
 149     ??? command line parsing!
 150
 151 4. git-debrebase release
 152
 153     stiches, finalises changelog, signs tags, pushes everything
 154     for the future, when there is some automatic builder
 155
 156 ========================================
 157
 158 import from gbp
 159
 160 what about dgit view branch ?
 161 ideally, would make pseudomerge over dgit view
 162 would need to check that dgit view is actually dgit view of
 163   ond of our ancestors
 164 failing that first push will need --overwrite
 165 that is what is currently implemented
 166
 167 ========================================
 168
 169 how to handle divergence and merges (if not detected soon enough)
 170
 171 same problem
 172  if merge, look at branches before merge
 173  generate new combined branch
 174  pseudomerge to overwrite merge
 175
 176 current avaiable strategies:
 177
 178  maybe launder foreign branch
 179
 180  if foreign branch is nmuish, can rebase it onto ours
 181
 182  could merge breakwaters (use analyse to find them)
 183  merge breakwaters (assuming same upstream)
 184  manually construct new patch queue by inspection of
 185   the other two patch queues
 186
 187  instead of manually constructing patch queue, could use
 188   gbp pq export and git merge the patch queues
 189   (ie work with interdiffs)
 190
 191  if upstreams are different and one is ahead
 192   simply treat that as "ours" and
 193   do the work to import changes from the other
 194
 195  if upstreams have diverged, can
 196   resolve somehow to make new upstream
 197   do new-upstream on each branch separately
 198   now reduced to previously "solved" problem
 199
 200  in future, auto patch queue merge algorithm
 201   determine next patch to apply
 202   there are three versions o..O, l..L, r..R
 203   we have already constructed m (previous patch or merged breakwater)
 204   try using vector calculus in the implied cube and compute
 205    multiple ways to check consistency ?
 206
 207 ========================================
 208
 209 For downstreams of Debian, sketch of git-ffqrebase
 210
 211 #    git-ffqrebase start [BASE]
 212 #                # records previous HEAD so it can be overwritten
 213 #                # records base for future git-ffqrebase
 214 #    git-ffqrebase set-base BASE
 215 #    git-ffqrebase <git-rebase options>
 216 #    git-ffqrebase finish
 217 #    git-ffqrebase status [BRANCH]