talk.txt

   1
   2 Hi.  I'm here to plug dgit, which is a tool (and infrastructure) for
   3 treating the Debian archive like a git remote.
   4
   5 I'm going to talk for about 35 minutess and then I'll take questions.
   6
   7 ----------------------------------------
   8
   9 When we work on Debian we take on different roles.  The biggest
  10 difference is between the maintainer (or maintainers) of a package,
  11 working on their own package, and everyone else.
  12
  13 I'm going to start by presenting dgit from the point of view of
  14 everyone else: NMUers, sponsorship, teams doing cross-archive work
  15 like transitions and reproducible builds, bug squashers, downstreams,
  16 users, and so on.
  17
  18
  19 The point of dgit is that it lets you treat the archive as if it were
  20 a git repository.
  21
  22 You can dgit clone any package, in any suite in the archive (so, for
  23 example, sid or experimental) and you will get a git tree which is
  24 exactly the same as dpkg-source -x.
  25
  26 You can then work on the package in git, the way you would work in git
  27 with any other project.  In particular, you can:
  28
  29  * commit on your local branch
  30  * cherry pick changes from other branches
  31  * git reset, git clean
  32  * git rebase -i to polish a more complex set of changes into
  33    a patch queue
  34
  35 If you want so share your work-in-progress with others, you can git
  36 push your branch anywhere where they will be able to fetch it.
  37
  38 If you have the right authority you can also dgit push, to upload
  39 (after doing a build).
  40
  41
  42 dgit is not a replacement for existing git packaging tools; it's
  43 intended to complement them.  So (unlike git-dpm) dgit does not define
  44 a git history structure, and (unlike git-buildpackage) it does not
  45 define a branch structure.  Nor does it require a particular source
  46 format.
  47
  48
  49 The dgit history structure is up to the maintainer.  If you are doing
  50 a straightforward NMU you should produce a well-structured linear
  51 sequence of commits, as you would for any git upstream.  If the
  52 package is using a quilty source format, you should not touch
  53 debian/patches; dgit will take care of updating the quilt patch stack.
  54
  55 Unless the maintainer uses dgit, the history you see in dgit will not
  56 be the maintainer's history.  This is because maintainers' git
  57 branches are often not identical to the source packages in the
  58 archive.
  59
  60 And, when dgit has to synthesise a git history because the maintainer
  61 is not using dgit, the history you see in dgit will have a very basic
  62 branch and commit structure, rather than representing the package's
  63 actual history.
  64
  65
  66 ----------------------------------------
  67
  68 Which brings me onto the other side of this talk: dgit for
  69 maintainers.
  70
  71 For the reasons I've explained, other dgit users would like you to use
  72 dgit for your maintainer uploads.  They will then be able to see, and
  73 directly work with, your own history.
  74
  75 But it's in your own interests, too:
  76
  77 If you use dgit, you will be able to directly merge and/or cherry-pick
  78 NMUs, patches proposed via pull-request emails, and so on: Because, in
  79 this case, the dgit-using contributor will have based their work on
  80 your own history.
  81
  82 Using dgit for your maintainer uploads will put your own history on
  83 browse.dgit.debian.org, rather than showing dgit's stub history (which
  84 can also be out of date).
  85
  86 If you use dgit push, you get an extra check that the source package
  87 you are uploading is exactly the same as your git HEAD.  This can
  88 save you some dsc-based checks.
  89
  90 And, of course, non-maintainer dgit users will thank you.
  91
  92
  93 dgit push imposes only two requirements on your git trees.  These stem
  94 directly from the need for the dgit view of package to be identical to
  95 the package as found in the archive.  The dgit view of every package
  96 needs to uniformly and directly useable.
  97
  98 The first, and most important, requirement is that your git tree is
  99 identical to the unpacked source package.  (Technically, in the case
 100 of a `3.0 (quilt)' package, it is what is sometimes called a `patches
 101 applied packaging branch without .pc'.)
 102
 103 For all native packages, and for users of git-dpm and raw git, this is
 104 already the interchange format.  These maintainers can start using
 105 dgit right away.  Please do!
 106
 107 For git-buildpackage users, things are a bit more complicated.  I'm
 108 told that gbp pq can be used to generate a patches-applied branch, and
 109 that some users prefer to use that as the interchange git branch.
 110
 111
 112 I mentioned that there were two requirements.  The other is simply
 113 that the dgit branch (one for each suite) is fast-forwarding.  So if
 114 you (or your workflow tool) generated a rebasing branch, you may need
 115 to do something like
 116    git merge -s ours dgit/sid
 117 before pushing.  I'm intending to provide some rather more cookied
 118 way to do this but I have decided the exact shape yet.
 119
 120
 121 ----------------------------------------
 122
 123 There are a few other things I ought to cover, since they often come
 124 up:
 125
 126
 127 The dgit view of the archive does not include the package upload
 128 history.  It is possible to use git-import-dscs to produce a git
 129 branch representing the upload history, but dgit does not do this
 130 itself.
 131
 132 There is nothing stopping anyone from pushing such a branch to the
 133 archive with dgit push.  But, it seems to me that the git history
 134 structure ought to up to the maintainer, and if the maintainer chooses
 135 to use dgit, normally the maintainers's existing git history is more
 136 useful and interesting.
 137
 138
 139 When using dgit, it is normally best to use one of dgit's build
 140 operations to build the package.  This is mainly because most other
 141 build tools by default remove .gitignore when generating the source
 142 package.  dgit requires that the source package and git tree are the
 143 same, so if your git tree has .gitignore in it, your source package
 144 should too.
 145
 146
 147 Many packages have strangely-behaved or plain buggy clean targets.
 148 Because dgit knows that your git tree is canonical, it can help work
 149 around this: you can tell dgit to use git clean instead, avoiding the
 150 package's clean target entirely.
 151
 152
 153 Some maintainers' source packages contain files not in their git
 154 branches: most commonly, autotools output.  Because the point of dgit
 155 is to provide a git view of what's actually in the archive, this does
 156 not work with dgit.
 157
 158 But nowadays most people seem to recommend that the package build
 159 should rerun autotools and regenerate these files, anyway.  If you do
 160 this, then neither your git tree nor your source package contain the
 161 autotools output and all is well.
 162
 163 Alternatively, you can commit the autotools output to git (and resolve
 164 any conflicts by simply rerunning autotools), or maintain a separate
 165 post-autotools git branch.
 166
 167
 168
 169
 170
 171 The point, of course, of using
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183  defer talking about
 184
 185