talk.txt

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