talk.txt

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