git-debrebase: wip: README

diff --git a/README.git-debrebase b/README.git-debrebase
new file mode 100644 (file)
index 0000000..8dcb0df
--- /dev/null
+++ b/README.git-debrebase
@@ -0,0 +1,78 @@
+From: Ian Jackson <ijackson@chiark.greenend.org.uk>
+To: Sean Whitton <spwhitton@spwhitton.name>
+Cc: debian-devel@lists.debian.org
+Subject: Re: Feedback on 3.0 source format problems
+Date: Fri, 6 Jan 2017 15:29:38 +0000
+
+Sean Whitton writes ("Re: Feedback on 3.0 source format problems"):
+> Could you explain in general terms the difference between the
+> interchange and packaging-only branches
+
+See modified diagram below.  Are the annotations I have added (and the
+name change) any help ?
+
+>  Does the packaging-only branch contain debian/ alone?
+
+No, it also contains a complete unmodified copy of the upstream code.
+(Except that if upstream had a debian/ directory, it is completely
+replaced.)  Perhaps this is the wrong name.  Let's try
+`merging-baseline'
+
+For `3.0 (quilt)' the merging-baseline branch contains roughly what
+you would get if you untarred the origs and the debian.tar.gz, and
+then deleted all the patches without applying them.
+
+Not shown on the diagram is the commit `add patch queue to
+debian/patches', which would be needed for `3.0 (quilt)'.  This is
+because the diagram is in terms of a sane source format, not `3.0
+(quilt)'.  For use with quilty sources, there would be such a commit
+(probably dgit-generated) on top of the actual upstream change
+commits:
+
+           ------/--A!----/--B3!--%--/--> interchange view
+                /        /          /      with debian/ directory
+               %        %          %       all upstream changes applied
+              /        /          /        3.0 (quilt) has debian/patches
+             /        2*         2*
+            /        /          /
+           2*       2          2
+          /        /          /
+         1        1          1    `merging-baseline' branch
+        /        /          /     unmodified upstream code
+    ---p-----p--A----p--B--C-->   plus debian/ (but no debian/patches)
+      /     /       /
+   --#-----#-------#-----> upstream
+
+    Key:
+
+      1,2,3   commits touching upstream files only
+      A,B,C   commits touching debian/ only
+      B3      mixed commit (eg made by an NMUer)
+      #       upstream releases
+
+     -p-      special merge, takes contents of debian/ from the
+     /         previous `merging-baseline' commit and rest from upstream
+
+     -/-      pseudomerge; contents are identical to
+     /         parent lower on diagram.
+
+      %       dgit-generated commit of debian/patches.
+              `3.0 (quilt)' only; dropped by rebase tool.
+
+      *       Maintainer's HEAD was here while they were editing,
+              before they said they were done, at which point their
+              tools generated [% and] -/- commit[s] to convert to
+              the fast-forwarding interchange branch.  (Maybe the
+              tooling is simply `dgit push'.)
+
+      !       NMUer's HEAD was here when they said `dgit push'.
+              Rebase branch launderer turns each ! into an
+              equivalent *.
+
+Ian.
+
+--
+Ian Jackson <ijackson@chiark.greenend.org.uk>   These opinions are my own.
+
+If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
+a private address which bypasses my fierce spamfilter.