notes

   1
   2 (PITCH)
   3
   4 [archive as vcs]
   5
   6 The Debian archive is 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.  So instead, let's build something
  21   to deal with the problems.
  22
  23   What that really means is that we need a better gateway.
  24
  25 [manpage]
  26
  27 dgit is a tool which lets you treat the archive as if it were a git
  28 server.
  29
  30 It provides uniform operation for all packages:
  31
  32 You can clone any package, work on it, build it, and upload it.
  33
  34 You don't need to know maintainer's workflow.  It doesn't matter
  35 whether the maintainer uses dgit, other git tools, quilt, CVS or SCCS.
  36
  37 With dgit you do all direct source code management in git.  As a dgit
  38 user you do not interact with the archive directly.
  39
  40 dgit is particularly useful for NMUers: you can prepare an RC bugfix,
  41 with full support from git, withut needing to know anything about the
  42 package's usual VCS arrangements.
  43
  44 [demo]
  45
  46 dgit also has great potential for downstreams - that is, derivatives
  47 and users who want to modify a package.  Having used dgit clone or
  48 fetch, you can merge into your downstream branch.  (There are some
  49 issues with this right now for non-DDs, which I'm going to discuss
  50 later.)
  51
  52 As a maintainer you can choose, if you like, to use the dgit git
  53 history as your primary working history.  Any fast forwarding
  54 patches-applied git workflow works with dgit.  In particular, you can
  55 have the full upstream git history in the ancestry if your dgit git
  56 history.
  57
  58
  59 (PRINCIPLES OF OPERATION)
  60
  61 [ .dsc, dpkg-source -x, git checkout, identity ]
  62
  63 This is Debian so you want to know how it works.  So let me run
  64 through dgit's principles of operation.  The data model is as follows:
  65
  66 A dgit-generated upload's .dsc contains a git commit hash.
  67 This specifies a commit whose tree is identical to the results of
  68 dpkg-source -x on the .dsc.
  69
  70 But the actual git history is not stored in the archive.  It is
  71 obtained via the git protocol from an actual git server.  (Currently
  72 this is on alioth but it's going to move.)
  73
  74 The only other constraint on the git commit named in the .dsc is that
  75 the successive dgit uploads must have a fast-forwarding history.
  76 Specifically, each upload made with dgit must have as an ancestor the
  77 current state of that package in the archive.
  78
  79 [ synthetic commit example ]
  80
  81 Non-dgit uploads don't have a (suitable) git commit hash.  But
  82 dgit clone needs to produce a suitable git commit.  It does this by
  83 inventing (in a deterministic way) a commit corresponding to the state
  84 of the archive.  If necessary, it also generates a synthetic merge
  85 commit to tie the invented commit into the previous dgit history.
  86
  87 (QUILTY WORKFLOW)
  88
  89 At the moment, dgit doesn't attempt to do anything clever with `3.0
  90 (quilt)' source packages.
  91
  92 The synthetic git history generated from non-dgit uploads does not
  93 represent the quilt patch stack.  And conversely, dgit push involves
  94 dpkg-source commit, to make the git tree be the same as dpkg-source
  95 would extract.  So dgit has to make some patches, and currently it
  96 makes single synthetic patch whose description contains some info from
  97 git log.
  98
  99 Overall this means that currently when you work on a quilty package in
 100 dgit, you don't interact with the quilt patch stack.  This is less
 101 than ideal and I intend to improve this, perhaps by having dgit use
 102 git-dpm as a bidirectional gateway between `3.0 (quilt)' and git.
 103
 104 This will generate a rebasing-style git branch.  After a patch series
 105 has been edited with rebase, dgit push will have to generate a `fake
 106 merge' commit to make the resulting history fast-forwarding.  (This is
 107 a well-understood git manipulation.)
 108
 109 (ACCESS PROBLEMS)
 110
 111 [table]
 112
 113
 114
 115   works well for DDs
 116   works badly for everyone else :-/
 117     serious problem, needs escalating
 118
 119   access limitations
 120
 121     ssh cocca psql -c SELECT BLAH
 122
 123       ftpmaster have a plan to help with this but has not been implemented
 124
 125     alioth collab-maint
 126
 127       push by signed tag
 128
 129       need to abandon alioth because of collab-maint security issues
 130
 131
 132 xxx adoption