git-debrebase: docs etc.: Intend to recognise anchors by commit annotation

[dgit.git] / NOTES.git-debrebase

diff --git a/NOTES.git-debrebase b/NOTES.git-debrebase
index 25410284ff86de42d832310e4ad000a4f59d3114..476120fd1e6c4f401e2d527d0961486ae84412e2 100644 (file)
--- a/NOTES.git-debrebase
+++ b/NOTES.git-debrebase
@@ -1,5 +1,17 @@
+TODO
+   recognise anchor merge by annotation, not just by structure
+
+   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 start [BASE]
 #                # records previous HEAD so it can be overwritten
 #                # records base for future git-ffqrebase


@@ -8,9 +20,7 @@
 #    git-ffqrebase finish
 #    git-ffqrebase status [BRANCH]
 #
 #    git-ffqrebase finish
 #    git-ffqrebase status [BRANCH]
 #

-#  refs/ffqrebase-prev/BRANCH    BRANCH may be refs/...; if not it means
-#  refs/ffqrebase-base/BRANCH      refs/heads/BRANCH
-#                               zero, one, or both of these may exist
+#  refs/ffq-prev/REF    relates to refs/REF

 #
 # git-debrebase without start, if already started, is willing
 # to strip pseudomerges provided that they overwrite exactly
 #
 # git-debrebase without start, if already started, is willing
 # to strip pseudomerges provided that they overwrite exactly


@@ -36,26 +46,29 @@ overall format
 [git-debrebase: split mixed commit, debian part]
 [git-debrebase: split mixed commit, upstream-part]
 [git-debrebase: convert dgit import, debian changes]
 [git-debrebase: split mixed commit, debian part]
 [git-debrebase: split mixed commit, upstream-part]
 [git-debrebase: convert dgit import, debian changes]

-[git-debrebase breakwater: convert dgit import, upstream changes]
+[git-debrebase anchor: convert dgit import, upstream changes]

 
 [git-debrebase upstream-combine . PIECE[ PIECE...]: new upstream]
 
 [git-debrebase upstream-combine . PIECE[ PIECE...]: new upstream]

-[git-debrebase breakwater: new upstream NEW-UPSTREAM-VERSION, merge]
+[git-debrebase anchor: new upstream NEW-UPSTREAM-VERSION, merge]

 [git-debrebase: new upstream NEW-UPSTREAM-VERSION, changelog]
 
 [git-debrebase: new upstream NEW-UPSTREAM-VERSION, changelog]
 

-[git-debrebase: gbp2debrebase, drop patches]
-[git-debrebase breakwater: declare upstream]
+[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)+)\]}
 
 
 m{^\[git-debrebase (?:\w*-)?upstream combine \.((?: $extra_orig_namepart_re)+)\]}
 

-Every breakwater commit must be a merge.  In principle, this is not
+Every anchor commit must be a merge.  In principle, this is not

 necessary.  After all, we are relying on the
 necessary.  After all, we are relying on the

-    [git-debrebase breakwater: ...]
-commit message annotation in "declare" breakwater merges (which
-do not have any upstream changes), to distinguish those breakwater
+    [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
 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 a breakwater base commit.  git-rebase
+don't want them to rewrite an anchor commit.  git-rebase

 trips up on merges, so that is a useful safety catch.
 
 
 trips up on merges, so that is a useful safety catch.
 
 


@@ -208,11 +221,11 @@ They should be made just before (ideally, part of) dgit push.
         (optionally, can use some other commit which is ff
          from all of the above, eg one of them)
 
         (optionally, can use some other commit which is ff
          from all of the above, eg one of them)
 

-N. git-debrebase record-ffrebase
+N. git-debrebase [--noop-ok] record-ffq-prev

 
      does what is described above
 
 
      does what is described above
 

-2. git-debrebase stitch [--noop-ok]
+2. git-debrebase [--noop-ok] stitch

 
     makes pseudomerge with will-overwrite
     deletes will-overwrite
 
     makes pseudomerge with will-overwrite
     deletes will-overwrite


@@ -233,7 +246,7 @@ N. git-debrebase record-ffrebase
 will-overwrite for each ref
     refs/heads/FOO
 is
 will-overwrite for each ref
     refs/heads/FOO
 is

-    refs/ffrebase/FOO
+    refs/ffq-prev/FOO

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


@@ -256,7 +269,7 @@ import from gbp
      new breakwater is
        old HEAD
        commit to remove d/patches
      new breakwater is
        old HEAD
        commit to remove d/patches

-       breakwater pseudomerge with upstream
+       anchor merge with upstream

        "rebase" of pq branch, each commit with d/patches stripped
 ]
 
        "rebase" of pq branch, each commit with d/patches stripped
 ]
 


@@ -266,5 +279,42 @@ would need to check that dgit view is actually dgit view of
   ond of our ancestors
 failing that first push will need --overwrite
 
   ond of our ancestors
 failing that first push will need --overwrite
 

-should this be called import or gbp2debrebase as it is now ?
-gbp uses "import" oddly but I'm tempted to use it normally here.
+========================================
+
+divergence, merges:
+
+same problem
+ if merge, look at branches before merge
+ generate new combined branch
+ pseudomerge to overwrite merge
+
+current avaiable strategies:
+
+ maybe launder foreign branch
+
+ if foreign branch is nmuish, can rebase it onto ours
+
+ could merge breakwaters (use analyse to find them)
+ merge breakwaters (assuming same upstream)
+ manually construct new patch queue by inspection of
+  the other two patch queues
+
+ instead of manually constructing patch queue, could use
+  gbp pq export and git merge the patch queues
+  (ie work with interdiffs)
+
+ if upstreams are different and one is ahead
+  simply treat that as "ours" and
+  do the work to import changes from the other
+
+ if upstreams have diverged, can
+  resolve somehow to make new upstream
+  do new-upstream on each branch separately
+  now reduced to previously "solved" problem
+
+ in future, auto patch queue merge algorithm
+  determine next patch to apply
+  there are three versions o..O, l..L, r..R
+  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 ?