NOTES.git-debrebase

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