git-debrebase(1): document record-ffq-prev

[dgit.git] / NOTES.git-debrebase

diff --git a/NOTES.git-debrebase b/NOTES.git-debrebase
index 32e5edfee655e9002c8559e7414f036755cfdfb8..7b9a9b19f39c4b7b3928991ae932d0c3fe0586c9 100644 (file)
--- a/NOTES.git-debrebase
+++ b/NOTES.git-debrebase
@@ -1,55 +1,14 @@
 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
+   clean up remains of README
 
    arrange for dgit to automatically stitch on push
 
-========================================
-
-#  refs/ffq-prev/REF    relates to refs/REF
-
-=======================================
-
-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)
@@ -72,6 +31,8 @@ workflow
 
 Theory for ffq-prev
 
+  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.
 
@@ -123,38 +84,14 @@ We check we are ff from remotes before recording new ffq-prev
 
   ---------- now follows much the same info in different words ----------
 
-1. git-debrebase [-i etc.]
-
-     should:
-        check for ffq-prev
-        if is already a ffq-prev, 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 ffq-prev 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 ffq-prev
-    deletes ffq-prev
+Re git-debrebase [--noop-ok] stitch
 
     we will teach dgit to do
        git-debrebase stitch
+    or some such ?
+
+following parts are not implemented and maybe aren't the
+best subcommand names etc.
 
 3. git-debrebase push
 
@@ -166,11 +103,6 @@ N. git-debrebase [--noop-ok] record-ffq-prev
     stiches, finalises changelog, signs tags, pushes everything
     for the future, when there is some automatic builder
 
-ffq-prev for each ref
-    refs/heads/FOO
-is
-    refs/ffq-prev/FOO
-
 ========================================
 
 import from gbp
@@ -224,6 +156,8 @@ current avaiable strategies:
 
 ========================================
 
+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