git-debrebase: Rename new-upstream-v0 command to new-upstream

[dgit.git] / NOTES.git-debrebase

diff --git a/NOTES.git-debrebase b/NOTES.git-debrebase
index 8613e407bce54654f5a3363ecd9bdef99217cea7..f87718b8df38216134524bc451f3792603cdc55e 100644 (file)
--- a/NOTES.git-debrebase
+++ b/NOTES.git-debrebase
@@ -1,76 +1,15 @@
 TODO
 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 ?
 
    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
    arrange for dgit to automatically stitch on push

+     dgit push usually needs to (re)make a pseudomerge.  The "first"
+     git-debrebase stripped out the previous pseudomerge and could
+     remembeed the old HEAD.  But the user has to manually stitch it.
+     To fix this, do we need a new push hook for dgit ?

 
 

-#    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]
-#
-#  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
-# 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
 
 
 workflow
 


@@ -79,23 +18,57 @@ workflow
   commit / git-debrebase / etc.
 
   dgit --damp-run push
   commit / git-debrebase / etc.
 
   dgit --damp-run push

-      hook: call git-debrebase prep-push   adds new pm ? passes --overwrite ?
-                                           dgit push does not update remote
+      hook: call git-debrebase prep-push   dgit push does not update remote
+      or something, must add patches at least

 
 

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

 
   dgit push
 
   dgit push

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

 
   commit / git-debrebase / etc.            strips last pm, but arranges
                                            that remade pm will incorporate it
 
 
 
   commit / git-debrebase / etc.            strips last pm, but arranges
                                            that remade pm will incorporate it
 
 

-==========
+# problems / outstanding questions:
+#
+#  *  dgit push with a `3.0 (quilt)' package means doing quilt
+#     fixup.  Usually this involves recommitting the whole patch
+#     series, one at a time, with dpkg-source --commit.  This is
+#     terribly terribly slow.  (Maybe this should be fixed in dgit.)
+#
+#  * Workflow is currently clumsy.  Lots of spurious runes to type.
+#    There's not even a guide.
+#
+#  * 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.
+#
+#  * 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.
+       
+
+# undocumented usages:
+#
+#    git-debrebase [<options>] downstream-rebase-launder-v0  # experimental
+
+
+========================================

 
 Theory for ffq-prev
 
 
 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.
 
 When we strip a pm, we need to maybe record it (or something) as the
 new start point.
 


@@ -145,40 +118,16 @@ When we do a thing
 
 We check we are ff from remotes before recording new ffq-prev
 
 
 We check we are ff from remotes before recording new ffq-prev
 

-========================================
-
-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
+  ---------- now follows much the same info in different words ----------

 
 

-    makes pseudomerge with ffq-prev
-    deletes ffq-prev
+Re git-debrebase [--noop-ok] stitch

 
     we will teach dgit to do
        git-debrebase 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
 
 
 3. git-debrebase push
 


@@ -190,45 +139,20 @@ N. git-debrebase [--noop-ok] record-ffq-prev
     stiches, finalises changelog, signs tags, pushes everything
     for the future, when there is some automatic builder
 
     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
 
 ========================================
 
 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
 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

+that is what is currently implemented

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

-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


@@ -265,3 +189,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]