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