chiark / gitweb /
i18n: Flag a handful of messages for translation
[dgit.git] / README.dsc-import
index ede7d9e..1ec53b0 100644 (file)
@@ -1,25 +1,23 @@
-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
-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
   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
+  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.
@@ -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
-  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.
 
-  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
-  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.
@@ -78,12 +71,16 @@ This has the following properties:
   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.
 
-* It is possible to `git-cherry-pick' etc. commits representing `3.0
+* 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
@@ -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.
 
-* 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
-  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)').