talk.txt

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