git-debrebase: explain why breakwater bases must be merges

[dgit.git] / NOTES.git-debrebase

diff --git a/NOTES.git-debrebase b/NOTES.git-debrebase
index c268d7598e265fb5a517e01c859e64651c7db3cb..95ad453e0c271d9aaa2a767df3e5be02060df02b 100644 (file)
--- a/NOTES.git-debrebase
+++ b/NOTES.git-debrebase
@@ -27,6 +27,38 @@
 #  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 breakwater: convert dgit import, upstream changes]
+
+[git-debrebase upstream-combine . PIECE[ PIECE...]: new upstream]
+[git-debrebase breakwater: new upstream NEW-UPSTREAM-VERSION, merge]
+[git-debrebase: new upstream NEW-UPSTREAM-VERSION, changelog]
+
+[git-debrebase: gbp2debrebase, drop patches]
+[git-debrebase breakwater: declare upstream]
+
+m{^\[git-debrebase (?:\w*-)?upstream combine \.((?: $extra_orig_namepart_re)+)\]}
+
+Every breakwater commit must be a merge.  In principle, this is not
+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
+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
+trips up on merges, so that is a useful safety catch.
+
+
 =========
 
 workflow
@@ -140,3 +172,31 @@ 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.
 
+========================================
+
+import from gbp
+
+ 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
+       breakwater pseudomerge 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