NOTES.git-debrebase

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