git-debrebase: merge: Use a fresh branch and check out again

[dgit.git] / NOTES.git-debrebase

diff --git a/NOTES.git-debrebase b/NOTES.git-debrebase
index b4ffdda23e760a98b165873470d9b8b6c4967f72..bd6e7151221f67ff54e6100f629c23ce58afaa55 100644 (file)
--- a/NOTES.git-debrebase
+++ b/NOTES.git-debrebase
@@ -1,285 +1,86 @@
-TODO
-   reference docs
-      git-debrebase(5)   data model
-      git-debrebase(1)   command line
-   tutorial
-      dgit-maint-debrebase(7)
-      someone should set branch.<name>.mergeOptions to include --ff-only ?
-
-   clean up remains of NOTES and README
-
-   arrange for dgit to automatically stitch on push
-
-#    git-ffqrebase start [BASE]
-#                # records previous HEAD so it can be overwritten
-#                # records base for future git-ffqrebase
-#    git-ffqrebase set-base BASE
-#    git-ffqrebase <git-rebase options>
-#    git-ffqrebase finish
-#    git-ffqrebase status [BRANCH]
+# problems / outstanding questions:

 #
 #

-#  refs/ffq-prev/REF    relates to refs/REF
+#  * new-upstream has an awkward UI for multiple upstream pieces.
+#    You end up with giant runic command lines.  Does this matter /
+#    One consequence of the lack of richness it can need -f in
+#    fairly sensible situations.

 #
 #

-# git-debrebase without start, if already started, is willing
-# to strip pseudomerges provided that they overwrite exactly
-# the previous HEAD
-#  xxxx is this right ?  what matters is have we pushed
-#    I think in fact the right answer is:
-#       git-debrebase always strips out pseudomerges from its branch
-#       a pseudomerge is put in at the time we want to push
-#       at that time, we make a pseudomerge of the remote tracking
-#           branch (if raw git) or the dgit view (if dgit)
-#       for raw git git-ffqrebase, do want preciseley to record
-#           value of remote tracking branch or our branch, on start, so we
-#           overwrite only things we intend to
-#  the previous pseudomerge    check for tags and remote branches ?
-
-
-=========
-
-special commit tags
-overall format
-  [git-debrebase[ COMMIT-TYPE [ ARGS...]]: PROSE, MORE PROSE]
-
-[git-debrebase: split mixed commit, debian part]
-[git-debrebase: split mixed commit, upstream-part]
-[git-debrebase: convert dgit import, debian changes]
-[git-debrebase anchor: convert dgit import, upstream changes]
-
-[git-debrebase upstream-combine . PIECE[ PIECE...]: new upstream]
-[git-debrebase anchor: new upstream NEW-UPSTREAM-VERSION, merge]
-[git-debrebase: new upstream NEW-UPSTREAM-VERSION, changelog]
-
-[git-debrebase convert-from-gbp: drop patches]
-[git-debrebase anchor: declare upstream]
-[git-debrebase pseudomerge: stitch]
-
-[git-debrebase convert-to-gbp: commit patches]
-
-m{^\[git-debrebase (?:\w*-)?upstream combine \.((?: $extra_orig_namepart_re)+)\]}
-
-Every anchor commit must be a merge.  In principle, this is not
-necessary.  After all, we are relying on the
-    [git-debrebase anchor: ...]
-commit message annotation in "declare" anchor merges (which
-do not have any upstream changes), to distinguish those anchor
-merges from ordinary pseudomerges (which we might just try to strip).
-
-However, the user is going to be doing git-rebase a lot.  We really
-don't want them to rewrite an anchor commit.  git-rebase
-trips up on merges, so that is a useful safety catch.
-
-
-=========
-
-workflow
-
-  git-debrebase blah [implies start]       strips pseudomerge(s)
-
-  commit / git-debrebase / etc.
+#  * There should be a good convention for the version number,
+#    and unfinalised or not changelog, after new-upstream.
+#
+#  * Handing of multi-orig dgit new-upstream .dsc imports is known to
+#    be broken.  They may be not recognised, improperly converted, or
+#    their conversion may be unrecognised.
+#
+#  * We need to develop a plausible model that works for derivatives,
+#    who probably want to maintain their stack on top of Debian's.
+#    downstream-rebase-launder-v0 may be a starting point?
+#    maybe the hypothetical git-ffqrebase is part of it too.
+       

 
 

-  dgit --damp-run push
-      hook: call git-debrebase prep-push   adds new pm ? passes --overwrite ?
-                                           dgit push does not update remote
+# undocumented usages:
+#
+#    git-debrebase [<options>] downstream-rebase-launder-v0  # experimental

 
 

-  commit / git-debrebase / etc.            strips pm(s) including last one

 
 

-  dgit push
-      hook: call git-debrebase prep-push   adds new pm ? passes --overwrite ?
-                                           dgit push DOES update remote
+========================================

 
 

-  commit / git-debrebase / etc.            strips last pm, but arranges
-                                           that remade pm will incorporate it
+Theory for ffq-prev

 
 

-Aha!
+  refs/ffq-prev/REF    relates to refs/REF

 
 When we strip a pm, we need to maybe record it (or something) as the
 new start point.
 
 
 When we strip a pm, we need to maybe record it (or something) as the
 new start point.
 

-We do this if the pm is contained within the output branch.
-
-Actually this is not special to PMs.
-
-We need to record a new to-be-overwritten commit
-   merge-base( our branch tip, relevant remote )
-
-If this is not a descendant of the relevant remote, then we are going
-to have a problem when we push so issue a warning or fail.
-
-
-
-How about
-
-  git-debrebase start or git-debrebase [continue]
-
-    with no recorded will-overwrite
-
-        putative will-overwrite is 
-            one model:
-                our current tip
-                obviously it is safe to say we will overwrite this
-                we do not need to worry about whether this will
-                    overwrite not-included changes in the remote
-                    because either the will-overwrite is not
-                    ff from the remote (in which case later failure,
-                    see below); or the will-overwrite _is_ ff
-                    from the remote ie our tip is later than the
-                    remote and includes all of its changes
+When we do a thing

 
 

-                this model tends to keep ad-hoc commits made on our
-                tip branch before we did rebase start, in the
-                `interchange view' and also in the rebase stack.
+    with no recorded ffq-prev

 
 

-            other model:
-                merge-base( current remote, current tip )
+        ffq-prev is our current tip

 
 

-                it is safe to overwrite current tip, by the
-                argument above
+        obviously it is safe to say we will overwrite this
+        we do check whether there are not-included changes in the remotes
+        because if the new ffq-prev is not ff from the remotes
+        the later pushes will fail

 
 

-                it is always safe to rewind will-overwrite: all
-                that does is overwrite _less_ stuff
+        this model tends to keep ad-hoc commits made on our
+        tip branch before we did rebase start, in the
+        `interchange view' and also in the rebase stack.

 
 

-                this is the earliest overwrite we can make that
-                    will be pushable to the remote
+        also we can explicitly preserve with
+        git-debrebase stitch

 
 

-                in practical terms this can only be ff from the
-                current remote if it is equal to the current remote;
-                so what we are actually checking below is that our tip
-                is ff from the remote.  This ought to be true before
-                the first of our rebases.
+       It is always safe to rewind ffq-prev: all
+       that does is overwrite _less_ stuff.

 
 

-                this model tends to rewind and rebase ad-hoc commits
-                made on our tip branch before we did rebase start,
-                this is better
-
-        in any case putative will-overwrite must be ff from remote.
+        in any case putative ffq-prev must be ff from remote.

         Otherwise when we push it will not be ff, even though we have
         Otherwise when we push it will not be ff, even though we have

-        made pseudomerge to overwrite will-overwrite.  So if we spot
-        this, report an error.
+        made pseudomerge to overwrite ffq-prev.  So if we spot
+        this, report an error.  see above

 
 

-    with a recorded will-overwrite
+    with a recorded ffq-prev

 
 

-        we may need to advance will-overwrite, to allow us to generate
+        we may need to advance ffq-prev, to allow us to generate

         future pseudomerges that will be pushable
 
         future pseudomerges that will be pushable
 

-        advancing will-overwrite is dangerous, since it might
+        advancing ffq-prev is dangerous, since it might

         effectively cancel the commits that will-ovewrite is advanced
         over.
 
         effectively cancel the commits that will-ovewrite is advanced
         over.
 

-        we advance it to merge-base( current remote, current tip )
+        ??? advance it to merge-base( current remote, current tip )

         if possible (see above), - ie to current remote, subject
         to the condition that that is an ancestor of current tip
 
         if possible (see above), - ie to current remote, subject
         to the condition that that is an ancestor of current tip
 

-In each case we can strip pseudomerges freely, as needed.  We do not
-want to record what pseudomerges we strip, because whether we need to
-keep them depends (only) on whether they have been pushed.
+        currently this is not implemented

 
 

-Is that actually true ?  What if the user actually _wanted_ to keep
-the pseudomerge despite not having pushed it ?
+        better maybe to detect divergence ?  but it is rather late
+        by then!

 
 

-In that case we need to advance will-overwrite past it.  We could
-provide an explicit command to do this: it would advance
-will-overwrite to the current tip (see rules above, which show that
-this is OK).  Or maybe to the last pseudomerge on the current tip,
-so that the overall result will be series of pseudomerges.
+We check we are ff from remotes before recording new ffq-prev

 
 ========================================
 
 
 ========================================
 

-So, pm handling specifics:
-
-strategy is to avoid making needless pseudomerges
-pseudomerges that exist will be preserved
-(by being included in will-overwrite)
-
-This is good because the presence of a pseudomerge means we know we
-want to keep it; and that allows explicit control over history detail
-level.
-
-It does mean we must avoid making the pseudomerges unnecessarily.
-They should be made just before (ideally, part of) dgit push.
-
-1. git-debrebase [-i etc.]
-
-     should:
-        check for will-overwrite
-        if is already a will-overwrite, fine, do no more
-        if not:
-
-        check our origin branch exists and we are ff from it
-        if not fail
-
-        check our other might-be-pushed to branches
-        check we are ff from them
-        if not fail
-
-        set will-overwrite to something which is ff from
-          all above branches
-
-        we use our tip, as discussed above
-        (optionally, can use some other commit which is ff
-         from all of the above, eg one of them)
-
-N. git-debrebase [--noop-ok] record-ffq-prev
-
-     does what is described above
-
-2. git-debrebase [--noop-ok] stitch
-
-    makes pseudomerge with will-overwrite
-    deletes will-overwrite
-
-    we will teach dgit to do
-       git-debrebase stitch
-
-3. git-debrebase push
-
-    like git push only does stitch first
-    ??? command line parsing!
-
-4. git-debrebase release
-
-    stiches, finalises changelog, signs tags, pushes everything
-    for the future, when there is some automatic builder
-
-will-overwrite for each ref
-    refs/heads/FOO
-is
-    refs/ffq-prev/FOO
-
-========================================
-
-import from gbp
-
-[ all this is done now:
- inputs:
-   current HEAD (patches-unapplied),
-     this is going to be the base of the old breakwater
-   nominated upstream
-
- checks:
-   HEAD:<upstream> = upstream:<upstream>
-   upstream..HEAD:<upstream> is empty (overrideable)
-   upstremm:debian is empty (overrideable)
-
- procedure:
-   construct
-     run gbp pq import to generate pq branch
-     new breakwater is
-       old HEAD
-       commit to remove d/patches
-       anchor merge with upstream
-       "rebase" of pq branch, each commit with d/patches stripped
-]
-
-what about dgit view branch ?
-ideally, would make pseudomerge over dgit view
-would need to check that dgit view is actually dgit view of
-  ond of our ancestors
-failing that first push will need --overwrite
-
-========================================
-
-divergence, merges:
+how to handle divergence and merges (if not detected soon enough)

 
 same problem
  if merge, look at branches before merge
 
 same problem
  if merge, look at branches before merge


@@ -316,3 +117,15 @@ current avaiable strategies:
   we have already constructed m (previous patch or merged breakwater)
   try using vector calculus in the implied cube and compute
    multiple ways to check consistency ?
   we have already constructed m (previous patch or merged breakwater)
   try using vector calculus in the implied cube and compute
    multiple ways to check consistency ?

+
+========================================
+
+For downstreams of Debian, sketch of git-ffqrebase
+
+#    git-ffqrebase start [BASE]
+#                # records previous HEAD so it can be overwritten
+#                # records base for future git-ffqrebase
+#    git-ffqrebase set-base BASE
+#    git-ffqrebase <git-rebase options>
+#    git-ffqrebase finish
+#    git-ffqrebase status [BRANCH]