1 files changed, 106 insertions, 0 deletions
diff --git a/README.dsc-import b/README.dsc-import
new file mode 100644
index 0000000..1ec53b0
--- /dev/null
+++ b/README.dsc-import
@@ -0,0 +1,106 @@
+We would like to: represent the input tarballs as a commit each (which
+all get merged together as if by git merge -s subtree), and for quilt
+packages, each patch as a commit.  But w want to avoid (as much as
+possible) reimplementing the package extraction algorithm in
+dpkg-source.
+
+dpkg-source does not currently provide interfaces that look like they
+are intended for what dgit wants to do.  And dgit wants to work with
+old versions of dpkg, so I have implemented the following algorithm
+rather than wait for such interfaces added (even supposing that a sane
+interface could be designed, which is doubtful):
+
+* dgit will untar each input tarball.
+
+  This will be done by scanning the .dsc for things whose names look
+  like (compressed) tarballs, and using the interfaces provided by
+  Dpkg::Compression to get at the tarball.
+
+  Each input tarball unpack will be done separately, and will be
+  followed by git add and git write-tree, to obtain a git tree object
+  corresponding to the tarball contents.
+
+  That tree object will be made into a commit object with no parents.
+  (The package changelog will be searched for the earliest version
+  with the right upstream version component, and the information found
+  there used for the commit object's metadata.)
+
+* For `3.0 (quilt), dgit will run
+    dpkg-source -x --skip-patches
+
+  git plumbing will be used to make the result into a tree and a
+  commit.  The commit will have as parents all the tarballs previously
+  mentioned.  The main orig tarball will be the leftmost parent and
+  the debian tarball the rightmost parent.  The metadata will come
+  from the .dsc and/or the final changelog entry.
+
+  dgit will then dpkg-source --before-build and record the resulting
+  tree, too.
+
+  Then, dgit will switch back to the patches-unapplied version and use
+  `gbp pq import' (in the private working area) to turn the
+  patches-unapplied tree into a patches-applied one.
+
+  Finally dgit will check that the gbp pq generated patches-applied
+  version has the same git tree object as the one generated by
+  dpkg-source --before-build.
+
+* For source formats other than `3.0 (quilt)', dgit will do simply
+    dpkg-source -x.
+
+  Again, it will make that into a tree and a commit.
+
+* For source formats with only single file entry in the .dsc, the
+  (one) tarball is not imported separately (since its tree object
+  would be the same as the extracted object), and the commit of the
+  dpkg-source -x output has no parents.
+
+* As currently, there will be a final no-change-to-the-tree
+  pseudomerge commit which stitches the package into the relevant dgit
+  suite branch.  (By `pseudomerge' we mean something that looks as if
+  it was made with git merge -s ours.)
+
+* As currently, dgit will take steps so that none of the git trees
+  discussed above contain a .pc directory.
+
+
+This has the following properties:
+
+* Each input tarball is represented by a different commit; in usual
+  cases these commits will be the same for every upload of the same
+  upstream version.
+
+* For `3.0 (quilt)' each patch's changes to the upstream files appears
+  as a single git commit (as is the effect of the debian tarball);
+  also, there is a commit object whose tree is just the debian/
+  directory, which might well be the same as certain debian-only git
+  workflow trees.
+
+* For `1.0' non-native, the effect of the diff is represented as a
+  commit.  So eg `git blame' will show synthetic commits corresponding
+  to the correct parts of the input source package.
+
+* It is possible to `git cherry-pick' etc. commits representing `3.0
+  (quilt)' patches.  It is even possible fish out the patch stack as
+  git branch and rebase it elsewhere etc., since the patch stack is
+  represented as a contiguous series of commits which make only the
+  relevant upstream changes.
+
+* Every orig tarball in the source package is decompressed twice, but
+  disk space for only one extra copy of its unpacked contents is
+  needed.  (The converse would be possible in principle but would be
+  very hard to arrange with the current interfaces provided by the
+  various tools.)
+
+* No back doors into the innards of dpkg-source (nor changes to
+  dpkg-dev) are required.
+
+* dgit does grow a dependency on git-buildpackage.
+
+* Knowledge of the source format embedded in dgit is is restricted to
+  some relatively straightforward processing of filenames found in
+  .dsc files.
+
+* dgit now depends on dpkg-source -x --skip-patches followed by
+  dpkg-source --before-build being the same as dpkg-source -x
+  (for `3.0 (quilt)').