README.dsc-import: Document actually-imported approach

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/README.dsc-import b/README.dsc-import
index ede7d9e3b299c154a3169739b48289119f3c501d..4bcf7fcc50c24513856fd9eb3383e68577fbf8f7 100644 (file)
--- a/README.dsc-import
+++ b/README.dsc-import
@@ -1,18 +1,16 @@
-I 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 I want
-to avoid (as much as possible) reimplementing the package extraction
-algorithm in dpkg-source.
+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
 
 dpkg-source does not currently provide interfaces that look like they

-are intended for what I want to do.  And dgit wants to work with old
-versions of dpkg, so I don't want to block on getting such interfaces
-added (even supposing that a sane interface could be designed, which
-is doubtful).
+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):

 
 

-So I intend to do as follows.  (Please hold your nose.)
-
-* dgit will untar each input tarball (other than the Debian tarball).
+* 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
 
   This will be done by scanning the .dsc for things whose names look
   like (compressed) tarballs, and using the interfaces provided by


@@ -31,41 +29,36 @@ So I intend to do as follows.  (Please hold your nose.)
     dpkg-source -x --skip-patches
 
   git plumbing will be used to make the result into a tree and a
     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 previous
-  mentioned.  The metadata will come from the .dsc and/or the final
-  changelog entry.
-
-  dgit will then see if it has a series file.  (dgit already rejects
-  packages with distro-specific series files, so we need worry only
-  about a single debian/patches/series file.)
-
-  If there is a series file, dgit will read it into memory.  It will
-  then iterate over the series file, and each time:
-    - write into its playground a series file containing one
-      more non-comment non-empty line to previously
-    - run dpkg-source --before-build (which will apply that
-      additional patch)
-    - make git tree and commit objects, using the metadata from
-      the relevant patch file to make the commit (if available)
-    - each commit object has as a parent the previous commit
-      (either the previous commit, or the commit resulting from
-      dpkg-source -x)
-
-  After this the series file has been completely rewritten in
-  this way, the tree should be identical to the results of
-  dpkg-source -x.
+  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.
 
 
 * 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.  (If this commit
-  has no changes in its tree from the first tarball commit. then the
-  two are squashed together.)
+  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
 
 * As currently, there will be a final no-change-to-the-tree
   pseudomerge commit which stitches the package into the relevant dgit

-  suite branch; ie something that looks as if it was made with git
-  merge -s ours.
+  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.
 
 * As currently, dgit will take steps so that none of the git trees
   discussed above contain a .pc directory.


@@ -78,8 +71,12 @@ This has the following properties:
   upstream version.
 
 * For `3.0 (quilt)' each patch's changes to the upstream files appears
   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).
-  For `1.0' non-native, the effect of the diff is represented as a
+  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.
 
   commit.  So eg `git blame' will show synthetic commits corresponding
   to the correct parts of the input source package.
 


@@ -98,25 +95,12 @@ This has the following properties:
 * No back doors into the innards of dpkg-source (nor changes to
   dpkg-dev) are required.
 
 * No back doors into the innards of dpkg-source (nor changes to
   dpkg-dev) are required.
 

-* dgit does grow a dependency on Dpkg::Compression.
+* dgit does grow a dependency on git-buildpackage.

 
 * Knowledge of the source format embedded in dgit is is restricted to
 
 * Knowledge of the source format embedded in dgit is is restricted to

-  iterating over tarballs and manipulating debian/patches/series,
-  which dgit already does.
-
-* dgit now depends on dpkg-source --before-build idempotently applying
-  patches as they successively appear on debian/patches/series.
-
-* Perhaps the git commits generated by dgit to represent patches can
-  be made to round-trip nicely into tools like git-dpm and
-  git-buildpackage.
-
-  I have found the information about tags in gbp-dch(1), but that
-  doesn't seem like it's applicable.
-
-  I have also found the information about tags in gbp-pq(1).  From
-  that it looks like I ought to generate "Gbp-Pq: Name" and "Gbp-Pq:
-  Topic".
+  some relatively straightforward processing of filenames found in
+  .dsc files.

 
 

-* The scheme I describe avoids introducing a dependency from dgit to
-  git-buildpackage.
+* 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)').

diff --git a/TODO.BRANCH b/TODO.BRANCH
index 580cc2158cc42d70bf7856d376cc6f682a5fc950..71323e32c9b8058ffc0b4c7ed4b6a987a937ceb3 100644 (file)
--- a/TODO.BRANCH
+++ b/TODO.BRANCH
@@ -4,8 +4,6 @@ OTHER
  * Replace quilt patch generation with git-format-patch output
    Honour (and strip) Gbp-Pq Topic and Gbp-Pq Name
 
  * Replace quilt patch generation with git-format-patch output
    Honour (and strip) Gbp-Pq Topic and Gbp-Pq Name
 

- * Fix up README.dsc-import to describe actual algorithm as implemented
-

  * Document --quilt=unapplied|gbp|dpm
 
 
  * Document --quilt=unapplied|gbp|dpm
 
 

diff --git a/dgit b/dgit
index 630c9f7441e707b37ffaea0021ba91c6a7a21652..1a5b88a5ef16284a0b09dc3affbb5e2fe0d119dc 100755 (executable)
--- a/dgit
+++ b/dgit
@@ -1566,6 +1566,7 @@ sub check_for_vendor_patches () {
 
 sub generate_commits_from_dsc () {
     # See big comment in fetch_from_archive, below.
 
 sub generate_commits_from_dsc () {
     # See big comment in fetch_from_archive, below.

+    # See also README.dsc-import.

     prep_ud();
     changedir $ud;
 
     prep_ud();
     changedir $ud;