README.dsc-import

   1 I would like to: represent the input tarballs as a
   2 commit each (which all get merged together as if by git merge -s
   3 subtree), and for quilt packages, each patch as a commit.  But I want
   4 to avoid (as much as possible) reimplementing the package extraction
   5 algorithm in dpkg-source.
   6
   7 dpkg-source does not currently provide interfaces that look like they
   8 are intended for what I want to do.  And dgit wants to work with old
   9 versions of dpkg, so I don't want to block on getting such interfaces
  10 added (even supposing that a sane interface could be designed, which
  11 is doubtful).
  12
  13 So I intend to do as follows.  (Please hold your nose.)
  14
  15 * dgit will untar each input tarball (other than the Debian tarball).
  16
  17   This will be done by scanning the .dsc for things whose names look
  18   like (compressed) tarballs, and using the interfaces provided by
  19   Dpkg::Compression to get at the tarball.
  20
  21   Each input tarball unpack will be done separately, and will be
  22   followed by git-add and git-write tree, to obtain a git tree object
  23   corresponding to the tarball contents.
  24
  25   That tree object will be made into a commit object with no parents.
  26   (The package changelog will be searched for the earliest version
  27   with the right upstream version component, and the information found
  28   there used for the commit object's metadata.)
  29
  30 * For `3.0 (quilt), dgit will run
  31     dpkg-source -x --skip-patches
  32
  33   git plumbing will be used to make the result into a tree and a
  34   commit.  The commit will have as parents all the tarballs previous
  35   mentioned.  The metadata will come from the .dsc and/or the final
  36   changelog entry.
  37
  38   dgit will then see if it has a series file.  (dgit already rejects
  39   packages with distro-specific series files, so we need worry only
  40   about a single debian/patches/series file.)
  41
  42   If there is a series file, dgit will read it into memory.  It will
  43   then iterate over the series file, and each time:
  44     - write into its playground a series file containing one
  45       more non-comment non-empty line to previously
  46     - run dpkg-source --before-build (which will apply that
  47       additional patch)
  48     - make git tree and commit objects, using the metadata from
  49       the relevant patch file to make the commit (if available)
  50     - each commit object has as a parent the previous commit
  51       (either the previous commit, or the commit resulting from
  52       dpkg-source -x)
  53
  54   After this the series file has been completely rewritten in
  55   this way, the tree should be identical to the results of
  56   dpkg-source -x.
  57
  58 * For source formats other than `3.0 (quilt)', dgit will do simply
  59     dpkg-source -x.
  60
  61   Again, it will make that into a tree and a commit.  (If this commit
  62   has no changes in its tree from the first tarball commit. then the
  63   two are squashed together.)
  64
  65 * As currently, there will be a final no-change-to-the-tree
  66   pseudomerge commit which stitches the package into the relevant dgit
  67   suite branch; ie something that looks as if it was made with git
  68   merge -s ours.
  69
  70 * As currently, dgit will take steps so that none of the git trees
  71   discussed above contain a .pc directory.
  72
  73
  74 This has the following properties:
  75
  76 * Each input tarball is represented by a different commit; in usual
  77   cases these commits will be the same for every upload of the same
  78   upstream version.
  79
  80 * For `3.0 (quilt)' each patch's changes to the upstream files appears
  81   as a single git commit (as is the effect of the debian tarball).
  82   For `1.0' non-native, the effect of the diff is represented as a
  83   commit.  So eg `git blame' will show synthetic commits corresponding
  84   to the correct parts of the input source package.
  85
  86 * It is possible to `git-cherry-pick' etc. commits representing `3.0
  87   (quilt)' patches.  It is even possible fish out the patch stack as
  88   git branch and rebase it elsewhere etc., since the patch stack is
  89   represented as a contiguous series of commits which make only the
  90   relevant upstream changes.
  91
  92 * Every orig tarball in the source package is decompressed twice, but
  93   disk space for only one extra copy of its unpacked contents is
  94   needed.  (The converse would be possible in principle but would be
  95   very hard to arrange with the current interfaces provided by the
  96   various tools.)
  97
  98 * No back doors into the innards of dpkg-source (nor changes to
  99   dpkg-dev) are required.
 100
 101 * dgit does grow a dependency on Dpkg::Compression.
 102
 103 * Knowledge of the source format embedded in dgit is is restricted to
 104   iterating over tarballs and manipulating debian/patches/series,
 105   which dgit already does.
 106
 107 * dgit now depends on dpkg-source --before-build idempotently applying
 108   patches as they successively appear on debian/patches/series.
 109
 110 * Perhaps the git commits generated by dgit to represent patches can
 111   be made to round-trip nicely into tools like git-dpm and
 112   git-buildpackage.
 113
 114   I have found the information about tags in gbp-dch(1), but that
 115   doesn't seem like it's applicable.
 116
 117   I have also found the information about tags in gbp-pq(1).  From
 118   that it looks like I ought to generate "Gbp-Pq: Name" and "Gbp-Pq:
 119   Topic".
 120
 121 * The scheme I describe avoids introducing a dependency from dgit to
 122   git-buildpackage.