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 ==== manpage 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
  54 ==== structure slide
  55 > include git-dpm, git, etc.
  56
  57 dgit is not a replacement for existing git packaging tools; it's
  58 intended to complement them.  So (unlike git-dpm) dgit does not define
  59 a git history structure, and (unlike git-buildpackage) it does not
  60 define a branch structure.  Nor does it require a particular source
  61 format.
  62
  63
  64 The dgit history structure is up to the maintainer.  If you are doing
  65 a straightforward NMU you should produce a well-structured linear
  66 sequence of commits, as you would for any git upstream.  If the source
  67 package is `3.0 (quilt)', you should not touch debian/patches; dgit
  68 will take care of that for you.
  69
  70 Unless the maintainer uses dgit, the history you see in dgit will not
  71 be the maintainer's history.  This is because maintainers' git
  72 branches often differ from the source packages in the archive.
  73
  74 So dgit may have to synthesise a git history.  The history you see in
  75 dgit will then have a very basic branch and commit structure, rather
  76 than representing the package's actual history.
  77
  78
  79 ==== history comparison slide
  80 > you use dgit
  81 > you don't use dgit
  82
  83 Which brings me onto the other side of this talk: dgit for
  84 maintainers.
  85
  86 For the reasons I've explained, downstream dgit users would like you
  87 to use dgit for your maintainer uploads.  They will then be able to
  88 see, and directly work with, your own history.
  89
  90 But it's in your own interests, too:
  91
  92 If you use dgit, you will be able to directly merge and/or cherry-pick
  93 NMUs, patches proposed via pull-request emails, and so on: Because, in
  94 this case, the dgit-using contributor will have based their work on
  95 your own history.
  96
  97 Using dgit for your maintainer uploads will put your own history on
  98 browse.dgit.debian.org, rather than showing dgit's stub history (which
  99 can also be out of date).
 100
 101 If you use dgit push, you get an extra check that the source package
 102 you are uploading is exactly the same as your git HEAD.  This can
 103 save you some dsc-based checks.
 104
 105 And, as I say, non-maintainer dgit users will thank you.
 106
 107
 108 ==== structure slide
 109 > with push requirement clearer
 110
 111 dgit push imposes only two requirements on your git trees.  These stem
 112 directly from dgit's design goals.
 113
 114 The most important requirement is that your git tree is identical to
 115 the unpacked source package.  (Technically, in the case of a `3.0
 116 (quilt)' package, it is what is sometimes called a `patches applied
 117 packaging branch without .pc'.)
 118
 119 For all native packages, and for users of git-dpm and raw git, this is
 120 already the interchange format.  These maintainers can start using
 121 dgit right away.  Please do!
 122
 123 For those using git-buildpackage with `3.0 (quilt)', things are a bit
 124 more complicated.  I'm told that gbp pq can be used to generate a
 125 patches-applied branch, and that some users prefer to use that as the
 126 interchange git branch.  I'm talking to the git-buildpackage
 127 maintainers about gbp integration.
 128
 129
 130 The other requirement of dgit is simply that the dgit branches are
 131 fast-forwarding.  So if your tools have made a rebasing branch, you
 132 may need to do something like
 133    git merge -s ours dgit/sid
 134 before pushing.  I'm intending to provide some rather more cooked
 135 way to do this but I have decided the exact shape yet.
 136
 137
 138 ==== structure diagram
 139 >
 140
 141 There are a few other things I ought to cover, since they often come
 142 up.  They're are relevant to maintainers and others:
 143
 144
 145 DMs currently need to email a signed copy of their ssh key, in order
 146 to be able to push.
 147
 148
 149 The dgit view does not generally include the package upload history.
 150 git-import-dscs can produce a git branch representing the upload
 151 history, but dgit does do that itself.
 152
 153 One could push such a branch to the archive with dgit push.  But, it
 154 seems to me that the git history structure ought to up to the
 155 maintainer, and if the maintainer chooses to use dgit, the
 156 maintainers's existing git history is probably better.
 157
 158
 159 It is normally best to use one of dgit's build operations to build for
 160 upload.  This is mainly because most other tools remove .gitignore by
 161 default.  dgit requires that the source package and git tree are the
 162 same, so if your git tree has .gitignore in it, your source package
 163 should too.
 164
 165
 166 Many packages have strangely-behaved or plain buggy clean targets.
 167 Because dgit knows that your git tree is canonical, it can help work
 168 around this: you can tell dgit to use git clean instead, avoiding the
 169 package's clean target entirely.
 170
 171
 172 Some maintainers' source packages contain files not in their git
 173 branches: most commonly, autotools output.  This is not compatible
 174 with dgit's purpose, namely to provide a git view of what's actually
 175 in the archive.
 176
 177 But nowadays most people recommend that the package build should
 178 always rerun autotools, anyway.  If you do that, then neither your git
 179 tree nor your source package need contain the autotools output and all
 180 is well.
 181
 182 Alternatively, you can commit the autotools output to git.
 183
 184
 185 ==== Future plans slide
 186 > DELAYED uploads
 187 >
 188 > automatic sending of the NMU diff email
 189 >
 190 > source-only one step push
 191 >
 192 > use of the dgit git repo server (other branches and tags) for general
 193 > purpose work
 194 >
 195 > more assistance for use with raw git
 196 >
 197 > automatic tracking of uploads into the dgit suite branches
 198 >
 199 >
 200 > help needed
 201 >
 202 > better workflow documentation for integration with existing git tools
 203 >
 204 > better gbp integration
 205 >
 206 > sponsor queue
 207
 208
 209 I have a number of plans for the future, some of which I need help
 210 with.  I don't have time I'm afraid to go through them now.
 211
 212 Instead, I'm going to open the talk up to questions now.