talk.txt

   1
   2 (PITCH)
   3
   4 [archive as vcs]
   5
   6 The Debian archive is (amongst other things) a version control system.
   7
   8   Clone (checkout) <=> apt-get source
   9   Commit+push <=> upload
  10
  11 But:
  12
  13   No sensible branching
  14   history browsing is appalling
  15   Terrible interaction with other VCSs
  16
  17 Solution
  18
  19 Well, we might replace it.  But the archive is various other things
  20 besides an appallingly bad VCS.  And a lot of our co-developers are
  21 used to it and fear and hate change.  So instead, we should have some
  22 software to help deal with the problem:
  23
  24 What that really means is that we need a better gateway.  That's what
  25 dgit is.
  26
  27 [manpage]
  28
  29 dgit is a tool which lets you treat the archive as if it were a git
  30 server.
  31
  32 It provides uniform operation for all packages:
  33
  34 You can clone any package, work on it, build it, and upload it.
  35
  36 You don't need to know maintainer's workflow.  It doesn't matter
  37 whether the maintainer uses dgit, other git tools, quilt, CVS or SCCS.
  38
  39 With dgit you do all direct source code management in git.  As a dgit
  40 user you do not interact with the archive directly.
  41
  42 dgit is particularly useful for NMUers: you can prepare an RC bugfix,
  43 with full support from git, withut needing to know anything about the
  44 package's usual VCS arrangements.
  45
  46 [demo]
  47
  48 dgit also has great potential for downstreams - that is, derivatives
  49 and users who want to modify a package.  Having used dgit clone or
  50 fetch, you can merge into your downstream branch.  (There are some
  51 issues with this right now for non-DDs, which I'm going to discuss
  52 later.)
  53
  54 As a maintainer you can choose, if you like, to use the dgit git
  55 history as your primary working history.  Any fast forwarding
  56 patches-applied git workflow works with dgit.  In particular, you can
  57 have the full upstream git history in the ancestry if your dgit git
  58 history.
  59
  60
  61 (PRINCIPLES OF OPERATION)
  62
  63 [ .dsc, dpkg-source -x, git checkout, identity ]
  64
  65 This is Debian so you want to know how it works.  So let me run
  66 through dgit's principles of operation.  The data model is as follows:
  67
  68 A dgit-generated upload's .dsc contains a git commit hash.
  69 This specifies a commit whose tree is identical to the results of
  70 dpkg-source -x on the .dsc.
  71
  72 But the actual git history is not stored in the archive.  It is
  73 obtained via the git protocol from an actual git server.  (Currently
  74 this is on alioth but it's going to move.)
  75
  76 The only other constraint on the git commit named in the .dsc is that
  77 the successive dgit uploads must have a fast-forwarding history.
  78 Specifically, each upload made with dgit must have as an ancestor the
  79 current state of that package in the archive.
  80
  81 [ synthetic commit example ]
  82
  83 Non-dgit uploads don't have a (suitable) git commit hash.  But
  84 dgit clone needs to produce a suitable git commit.  It does this by
  85 inventing (in a deterministic way) a commit corresponding to the state
  86 of the archive.  If necessary, it also generates a synthetic merge
  87 commit to tie the invented commit into the previous dgit history.
  88
  89 (QUILTY WORKFLOW)
  90
  91 [ synthetic patch example ]
  92
  93 At the moment, dgit doesn't attempt to do anything clever with `3.0
  94 (quilt)' source packages.
  95
  96 The synthetic git history generated from non-dgit uploads does not
  97 represent the quilt patch stack.  And conversely, dgit push involves
  98 dpkg-source commit, to make the git tree be the same as dpkg-source
  99 would extract.  So dgit has to make some patches, and currently it
 100 makes single synthetic patch whose description contains some info from
 101 git log.
 102
 103 Overall this means that currently when you work on a quilty package in
 104 dgit, you don't interact with the quilt patch stack.  This is less
 105 than ideal.
 106
 107 I intend to improve this, perhaps by having dgit use git-dpm as a
 108 bidirectional gateway between `3.0 (quilt)' and git.  Exactly how to
 109 do this involves some complicated design decisions which I haven't
 110 entirely worked out yet.  The intent, though, is that there will be an
 111 option to generate a rebasing-style git branch.  After a patch series
 112 has been edited with rebase, dgit push will generate a `fake merge'
 113 commit to make the resulting history fast-forwarding.
 114
 115 (ACCESS PROBLEMS)
 116
 117 [table]
 118
 119 Probably the biggest problem with dgit right now is that it is only
 120 useable for DDs.  This is particularly galling for a tool which is
 121 especially useful for users, downstreams, mentees, and so forth.
 122
 123 There are two obstacles to widening the access, one relating to the
 124 archive and one to the git server.
 125
 126 Firstly, dgit needs to query the archive to find the current version
 127 of the package and obtain a copy of the .dsc.  At the moment there is
 128 no official interface which provides this data.  There is the rmadison
 129 server but it sometimes serves stale or wrong data and there is no
 130 authentication - that is, there is no way for the client to tell that
 131 the data is accurate.  So what dgit does right now is ssh to coccia
 132 and run SQL commands against its mirror of the ftpmaster database.
 133 This is obviously mad.  ftpmaster have promised me a proper query
 134 service API (via HTTP and TLS).
 135
 136 Secondly, dgit is currently using alioth as its git server, and the
 137 collab-maint group there for authentication.  This is not ideal for a
 138 number of reasons.  Alioth does a lot of other things and is therefore
 139 less secure and reliable than would be ideal.  dgit's required
 140 authentication model is not a very good fit for alioth's
 141 infrastructure.  We intend to move this to a VM of its own - I've
 142 spoken to DSA (in the person of Tollef) about this.
 143