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 (so, for example, sid or
  35 experimental) and you will get a git tree which is exactly the same as
  36 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 ==== history comparison slide
  76
  77 For the reasons I've explained, downstream dgit users would like you
  78 to use dgit push.  They will then be able to see, and directly work
  79 with, your own history.
  80
  81 But it's in your own interests, too:
  82
  83 If you use dgit, you will be able to directly merge NMUs, patches
  84 proposed via pull-request emails, and so on: Because, in this case,
  85 the dgit-using contributor will have based their work on your own
  86 history.
  87
  88 Using dgit for your maintainer uploads will put your own history on
  89 browse.dgit.debian.org, rather than advertising dgit's stub history
  90 (which can also be out of date).
  91
  92 If you use dgit push, you get an extra check that the source package
  93 you are uploading is exactly the same as your git HEAD.  This can
  94 save you some dsc-based checks.
  95
  96 And, as I say, non-maintainer dgit users will thank you.
  97
  98
  99 ==== data flow slide with EQUAL and FF
 100
 101 dgit is not a replacement for existing git packaging tools; it's
 102 intended to complement them.  So (unlike git-dpm) dgit does not define
 103 a git history structure; nor does it define a branch structure or
 104 require a particular source format.
 105
 106
 107 dgit push imposes only two requirements on your git trees, which stem
 108 directly from dgit's goals.
 109
 110 The most important requirement is that your git tree is identical to
 111 the unpacked source package.  (Technically, in the case of a `3.0
 112 (quilt)' package, it is what is sometimes called a `patches-applied
 113 packaging branch without .pc'.)
 114
 115 For all native packages, and for users of git-dpm and raw git, this is
 116 already the interchange format.  These maintainers can start using
 117 dgit right away.  Please do!
 118
 119 For those using git-buildpackage with `3.0 (quilt)', things are a bit
 120 more complicated.  I'm told that gbp pq can be used to generate a
 121 patches-applied branch, and that some users prefer to use that as the
 122 interchange git branch.  I'm talking to the git-buildpackage
 123 maintainers about gbp integration.
 124
 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.
 142
 143
 144 The dgit view does not generally include the package upload history.
 145 git-import-dscs can produce a git branch representing the upload
 146 history, but dgit doesn't run that itself.
 147
 148 One could push such a branch to the archive with dgit push.  But, it
 149 seems to me that the git history structure ought to up to the
 150 maintainer, and if the maintainer chooses to use dgit, the
 151 maintainers's existing git history is probably better.
 152
 153
 154 It is normally best to use one of dgit's build operations to build for
 155 upload.  This is mainly because most other tools remove .gitignore by
 156 default.  dgit requires that the source package and git tree are the
 157 same, so if your git tree has .gitignore in it, your source package
 158 should too.
 159
 160
 161 Many packages have strangely-behaved or plain buggy clean targets.
 162 Because dgit knows that your git tree is canonical, it can help work
 163 around this: you can tell dgit to use git clean instead, avoiding the
 164 package's clean target entirely.
 165
 166
 167 Some source packages contain files not in the maintainers' git
 168 branches, and which are needed to build: most commonly, autotools
 169 output.  Such git branches are not useable with dgit.
 170
 171 But nowadays most people recommend that the package build should
 172 always rerun autotools.  If you do that, then neither your git tree
 173 nor your source package need contain the autotools output and all is
 174 well.
 175
 176 Alternatively, you can commit the autotools output to git.
 177
 178
 179 ==== Future plans slide
 180 > DELAYED uploads
 181 >
 182 > automatic sending of the NMU diff email
 183 >
 184 > one step source-only push/upload
 185 >
 186 > use of the dgit git repo server (other branches and tags) for general
 187 > purpose work
 188 >
 189 > better tooling assistance for use with raw git-rebase
 190 >
 191 > automatic mirroring into the dgit git branches of non-dgit uploads
 192 >
 193 >
 194 > help needed
 195 >
 196 > better workflow documentation for integration with existing git
 197 > tools (esp. re NMU integration and new upstream version handling).
 198 >
 199 > better gbp integration
 200 >
 201 > sponsor queue
 202
 203
 204 I have a number of plans for the future, some of which I need help
 205 with.  But I don't have time, I'm afraid, to go through them.
 206
 207 Instead, I'm going to open the talk up to questions now.