NOTES.git-debrebase

   1 TODO
   2    reference docs
   3       git-debrebase(5)   data model
   4       git-debrebase(1)   command line
   5    tutorial
   6       dgit-maint-debrebase(7)
   7       someone should set branch.<name>.mergeOptions to include --ff-only ?
   8
   9    clean up remains of NOTES and README
  10
  11    arrange for dgit to automatically stitch on push
  12
  13 #    git-ffqrebase start [BASE]
  14 #                # records previous HEAD so it can be overwritten
  15 #                # records base for future git-ffqrebase
  16 #    git-ffqrebase set-base BASE
  17 #    git-ffqrebase <git-rebase options>
  18 #    git-ffqrebase finish
  19 #    git-ffqrebase status [BRANCH]
  20 #
  21 #  refs/ffq-prev/REF    relates to refs/REF
  22 #
  23 # git-debrebase without start, if already started, is willing
  24 # to strip pseudomerges provided that they overwrite exactly
  25 # the previous HEAD
  26 #  xxxx is this right ?  what matters is have we pushed
  27 #    I think in fact the right answer is:
  28 #       git-debrebase always strips out pseudomerges from its branch
  29 #       a pseudomerge is put in at the time we want to push
  30 #       at that time, we make a pseudomerge of the remote tracking
  31 #           branch (if raw git) or the dgit view (if dgit)
  32 #       for raw git git-ffqrebase, do want preciseley to record
  33 #           value of remote tracking branch or our branch, on start, so we
  34 #           overwrite only things we intend to
  35 #  the previous pseudomerge    check for tags and remote branches ?
  36
  37
  38 =========
  39
  40 special commit tags
  41 overall format
  42   [git-debrebase[ COMMIT-TYPE [ ARGS...]]: PROSE, MORE PROSE]
  43
  44 [git-debrebase: split mixed commit, debian part]
  45 [git-debrebase: split mixed commit, upstream-part]
  46 [git-debrebase: convert dgit import, debian changes]
  47 [git-debrebase anchor: convert dgit import, upstream changes]
  48
  49 [git-debrebase upstream-combine . PIECE[ PIECE...]: new upstream]
  50 [git-debrebase anchor: new upstream NEW-UPSTREAM-VERSION, merge]
  51 [git-debrebase: new upstream NEW-UPSTREAM-VERSION, changelog]
  52
  53 [git-debrebase convert-from-gbp: drop patches]
  54 [git-debrebase anchor: declare upstream]
  55 [git-debrebase pseudomerge: stitch]
  56
  57 [git-debrebase convert-to-gbp: commit patches]
  58
  59 m{^\[git-debrebase (?:\w*-)?upstream combine \.((?: $extra_orig_namepart_re)+)\]}
  60
  61 Every anchor commit must be a merge.  In principle, this is not
  62 necessary.  After all, we are relying on the
  63     [git-debrebase anchor: ...]
  64 commit message annotation in "declare" anchor merges (which
  65 do not have any upstream changes), to distinguish those anchor
  66 merges from ordinary pseudomerges (which we might just try to strip).
  67
  68 However, the user is going to be doing git-rebase a lot.  We really
  69 don't want them to rewrite an anchor commit.  git-rebase
  70 trips up on merges, so that is a useful safety catch.
  71
  72
  73 =========
  74
  75 workflow
  76
  77   git-debrebase blah [implies start]       strips pseudomerge(s)
  78
  79   commit / git-debrebase / etc.
  80
  81   dgit --damp-run push
  82       hook: call git-debrebase prep-push   adds new pm ? passes --overwrite ?
  83                                            dgit push does not update remote
  84
  85   commit / git-debrebase / etc.            strips pm(s) including last one
  86
  87   dgit push
  88       hook: call git-debrebase prep-push   adds new pm ? passes --overwrite ?
  89                                            dgit push DOES update remote
  90
  91   commit / git-debrebase / etc.            strips last pm, but arranges
  92                                            that remade pm will incorporate it
  93
  94
  95 ==========
  96
  97 Theory for ffq-prev
  98
  99 When we strip a pm, we need to maybe record it (or something) as the
 100 new start point.
 101
 102 When we do a thing
 103
 104     with no recorded ffq-prev
 105
 106         ffq-prev is our current tip
 107
 108         obviously it is safe to say we will overwrite this
 109         we do check whether there are not-included changes in the remotes
 110         because if the new ffq-prev is not ff from the remotes
 111         the later pushes will fail
 112
 113         this model tends to keep ad-hoc commits made on our
 114         tip branch before we did rebase start, in the
 115         `interchange view' and also in the rebase stack.
 116
 117         also we can explicitly preserve with
 118         git-debrebase stitch
 119
 120         It is always safe to rewind ffq-prev: all
 121         that does is overwrite _less_ stuff.
 122
 123         in any case putative ffq-prev must be ff from remote.
 124         Otherwise when we push it will not be ff, even though we have
 125         made pseudomerge to overwrite ffq-prev.  So if we spot
 126         this, report an error.  see above
 127
 128     with a recorded ffq-prev
 129
 130         we may need to advance ffq-prev, to allow us to generate
 131         future pseudomerges that will be pushable
 132
 133         advancing ffq-prev is dangerous, since it might
 134         effectively cancel the commits that will-ovewrite is advanced
 135         over.
 136
 137         ??? advance it to merge-base( current remote, current tip )
 138         if possible (see above), - ie to current remote, subject
 139         to the condition that that is an ancestor of current tip
 140
 141         currently this is not implemented
 142
 143         better maybe to detect divergence ?  but it is rather late
 144         by then!
 145
 146 We check we are ff from remotes before recording new ffq-prev
 147
 148 ========================================
 149
 150 1. git-debrebase [-i etc.]
 151
 152      should:
 153         check for ffq-prev
 154         if is already a ffq-prev, fine, do no more
 155         if not:
 156
 157         check our origin branch exists and we are ff from it
 158         if not fail
 159
 160         check our other might-be-pushed to branches
 161         check we are ff from them
 162         if not fail
 163
 164         set ffq-prev to something which is ff from
 165           all above branches
 166
 167         we use our tip, as discussed above
 168         (optionally, can use some other commit which is ff
 169          from all of the above, eg one of them)
 170
 171 N. git-debrebase [--noop-ok] record-ffq-prev
 172
 173      does what is described above
 174
 175 2. git-debrebase [--noop-ok] stitch
 176
 177     makes pseudomerge with ffq-prev
 178     deletes ffq-prev
 179
 180     we will teach dgit to do
 181        git-debrebase stitch
 182
 183 3. git-debrebase push
 184
 185     like git push only does stitch first
 186     ??? command line parsing!
 187
 188 4. git-debrebase release
 189
 190     stiches, finalises changelog, signs tags, pushes everything
 191     for the future, when there is some automatic builder
 192
 193 ffq-prev for each ref
 194     refs/heads/FOO
 195 is
 196     refs/ffq-prev/FOO
 197
 198 ========================================
 199
 200 import from gbp
 201
 202 [ all this is done now:
 203  inputs:
 204    current HEAD (patches-unapplied),
 205      this is going to be the base of the old breakwater
 206    nominated upstream
 207
 208  checks:
 209    HEAD:<upstream> = upstream:<upstream>
 210    upstream..HEAD:<upstream> is empty (overrideable)
 211    upstremm:debian is empty (overrideable)
 212
 213  procedure:
 214    construct
 215      run gbp pq import to generate pq branch
 216      new breakwater is
 217        old HEAD
 218        commit to remove d/patches
 219        anchor merge with upstream
 220        "rebase" of pq branch, each commit with d/patches stripped
 221 ]
 222
 223 what about dgit view branch ?
 224 ideally, would make pseudomerge over dgit view
 225 would need to check that dgit view is actually dgit view of
 226   ond of our ancestors
 227 failing that first push will need --overwrite
 228
 229 ========================================
 230
 231 divergence, merges:
 232
 233 same problem
 234  if merge, look at branches before merge
 235  generate new combined branch
 236  pseudomerge to overwrite merge
 237
 238 current avaiable strategies:
 239
 240  maybe launder foreign branch
 241
 242  if foreign branch is nmuish, can rebase it onto ours
 243
 244  could merge breakwaters (use analyse to find them)
 245  merge breakwaters (assuming same upstream)
 246  manually construct new patch queue by inspection of
 247   the other two patch queues
 248
 249  instead of manually constructing patch queue, could use
 250   gbp pq export and git merge the patch queues
 251   (ie work with interdiffs)
 252
 253  if upstreams are different and one is ahead
 254   simply treat that as "ours" and
 255   do the work to import changes from the other
 256
 257  if upstreams have diverged, can
 258   resolve somehow to make new upstream
 259   do new-upstream on each branch separately
 260   now reduced to previously "solved" problem
 261
 262  in future, auto patch queue merge algorithm
 263   determine next patch to apply
 264   there are three versions o..O, l..L, r..R
 265   we have already constructed m (previous patch or merged breakwater)
 266   try using vector calculus in the implied cube and compute
 267    multiple ways to check consistency ?