NOTES.git-debrebase

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