like transitions and reproducible builds, and so on. Maintainers, please be patient - I'll get to you.
-==== data flow slide
+==== manpage slide
The point of dgit is that it lets everyone treat the archive as if it
were a git repository.
experimental) and you will get a git tree which is exactly the same as
dpkg-source -x.
+So dgit always works the same, from the non-maintainer's point of
+view, on any package: the operation is completely uniform. You don't
+need to know anything about the maintainer's verson control workflow
+tools or source format preferences.
+
You can then work on the package in git, the way you would work in git
with any other project. In particular, you can:
* all of the usual gitish stuff
If you have the right authority you can also dgit push, to upload.
-You still have to do a build.
+That is, a DD can dgit push any package; a DM can dgit push the
+packages that the archive thinks they can upload.
+
+Before you push you still have to do a build. dgit does not replace
+existing ways of building source and binary packages, although it does
+provide some helpful build rune wrappers (more about that later).
+
+
+If you don't want to, or can't, upload to Debian, but do want so share
+your work-in-progress with other people, you can git push your dgit
+branch anywhere suitable, so they can fetch it. So, for example, you
+could share your branch with your sponsor, who could then approve it
+by running dgit push. dgit's branches are ordinary git branches for
+this purpose.
+
+==== data flow slide
+
+Behind the scenes, dgit works by providing a set of git repositories
+in parallel to the existing archive.
+
+Every dgit push is actually two underlying operations: the first is a
+git tag and push, to the dgit git server. The second is a
+conventional package upload - with a wrinkle: the .dsc of an upload
+done with dgit contains the git commit hash that was pushed.
+
+Likewise, fetch and clone combine information from the archive and the
+git history. If the most recent upload was done with dgit, the commit
+hash in the dsc enables dgit fetch to find the right commit and
+present it to you. If the most recent upload was not done with dgit,
+dgit imports the source package into git - and stitches it into the
+existing dgit history, if there is one.
+
+You do need to dgit branches a bit specially is if you need to build
+source pacakges (for upload, for example). In this case dgit needs
+the .orig tarballs for your source package. If you are not doing a
+new upstream version, dgit fetch will get the relevant .origs for you.
+If you are, then presumably you have obtained them as part of
+preparing your package, or can build them easily.
-If you want so share your work-in-progress with others, you can git
-push your branch anywhere suitable, so they can fetch it. So, for
-example, you could share your branch with your sponsor, who could
-then approve it by running dgit push.
==== NMU linear history slide
-The dgit history structure is up to the maintainer. If you are doing
-a straightforward NMU you should produce a well-structured linear
-sequence of commits, as you would for any other git upstream. If the
-source package is `3.0 (quilt)', you shouldn't touch debian/patches;
-dgit will take care of that for you.
+As a general rule, the dgit history structure should be up to the
+maintainer - at least, if they care.
+
+If you are doing a straightforward NMU you should produce a
+well-structured linear sequence of commits, as you would for any other
+git upstream. Not only does this mean that if the maintainer is using
+dgit, they can hopefully easily include your changes; it also means
+that if they _aren't_ using dgit, at least you have published a
+history which is suitable for rebasing onto theirs, or whatever.
+
+If the source package is `3.0 (quilt)', you shouldn't touch
+debian/patches; dgit will take care of that for you. This is the
+other reason why you should provide a tidy linear patch series: if the
+maintainer likes quilt and is not using dgit, your changes will be
+automatically presented to them in a fairly plausible format.
+
+An ordinary NMUer should not normally update a patch in the quilt
+stack directly. Ie, an NMUer shouldn't squash their changes into an
+existing patch. This is because while it's easy for the maintainer to
+squash it themselves, if they want, it's a little harder for the
+maintainer to disentangle a squashed patch. This can also result in
+people having to read interdiffs, which are notoriously confusing.
+
==== NMU linear history on top of basic dgit history
Sadly, unless the maintainer uses dgit, the history you see in dgit
-will not be the maintainer's history. This is because maintainers'
-git branches often differ from the source packages in the archive.
+will not be the maintainer's history.
+
+This is because maintainers' git branches often differ from the source
+packages in the archive.
+
+If you dgit clone a package and it has an X-Vcs-Git header, dgit will
+set up a remote for it, so you can fetch the history and use it if you
+like. So in that sense dgit clone encompasses debcheckout.
+
+But, in the general case, the X-Vcs-Git tree may not be immediately
+useable to someone not familiar with the package.
+
+The maintainer's repo might contain only a debian/ directory, or be a
+quilty tree without patches applied. And the tag and suite naming
+conventions can vary too. So while the maintainer's history can be
+useful if you want to do archeaology, it's not in general suitable for
+use by dgit.
+
+There is also the problem that the maintainer's nominated git server
+might be anywhere, so it might be down, or gone away, or compromised.
-So dgit may have to synthesise a git history. The history you see in
-dgit will then have a very basic branch and commit structure, rather
-than representing the package's actual history.
+
+So, if the maintainer is not using dgit, dgit has to synthesise a git
+history. The history you see in dgit will then have a very basic
+branch and commit structure, rather than representing the package's
+actual history.
Which brings me onto the other side of this talk: dgit for
==== history comparison slide
For the reasons I've explained, downstream dgit users would like you
-as a maintainer
-to use dgit push to do your uploads. They will then be able to see, and directly work
-with, your own history.
+as a maintainer to use dgit push to do your uploads. They will then
+be able to see, and directly work with, your own history.
+
+In general, the point of using a dvcs like git is to publish your
+work. The existing ways of publishing git histories for Debian
+packagess aren't uniformly useable for users: they require the user to
+understand the maintainer's git working practices.
+
+What dgit does is provide a way for you to publish a history which
+users can rely on actually corresponding to the archive, and use
+immediately without special knowledge.
-But it's in your own interests, too:
+But it's in your own interest to upload with dgit, too:
If you use dgit, you will be able to directly merge NMUs, patches
proposed via pull-request emails, and so on: Because, in this case,
the dgit-using contributor will have based their work on your own
-history.
+history. Whereas, if you don't, dgit-using contributors will be
+working on a stub history, and may dgit push commits based on that
+stub. You can dgit fetch it even if you're not using dgit for your
+uploads, but when you do at the very least you'll have to rebase the
+NMUer's work.
-Using dgit for your maintainer uploads will put your own history on
-browse.dgit.debian.org, rather than advertising dgit's stub history
-(which can also be out of date).
+Another advantage of using dgit for your maintainer uploads is that it
+will put your own history on browse.dgit.debian.org, rather than
+advertising dgit's stub history (which can also be out of date).
If you use dgit push, you get an extra check that the source package
you are uploading is exactly the same as your git HEAD. This can
save you some dsc-based checks.
-And, as I say, non-maintainer dgit users will thank you.
+And, of course, as I say, doing your uploads with dgit will improve
+downstream dgit users' lives.
==== data flow slide
dgit is not a replacement for existing git packaging tools; it's
intended to complement them. So (unlike git-dpm) dgit does not define
-a git history structure; nor does it define a branch structure or
-require a particular source format.
+a git history structure.
+
+Nor does dgit define a branch structure distinguishing upstream or
+downstream branches, pristine tar branches, etc.
+
+dgit doesn't require a particular source format; it couldn't, since it
+needs to work with any package.
==== data flow slide with EQUAL and FF
dgit push imposes only two requirements on your git trees, which stem
-directly from dgit's goals.
+directly from dgit's objectives.
The most important requirement is that your git tree is identical to
the unpacked source package. (Technically, in the case of a `3.0
(quilt)' package, it is what is sometimes called a `patches-applied
-packaging branch without .pc directory', if you know what that means.)
+packaging branch without .pc directory'.)
For all native packages, and for users of git-dpm and raw git, this is
already the interchange format. These maintainers can start using
talking to the git-buildpackage maintainers about gbp integration, so
watch this space.
-xxx slide
+xxx slide ?
The other requirement of dgit is simply that the dgit branches are
fast-forwarding. So if your tools have made a rebasing branch, you
-may need to do something like
- git merge -s ours dgit/sid
-before pushing. I'm intending to provide some rather more cooked
-way to do this but I haven't decided the exact shape yet.
+may need to make a fake merge (with git merge -s ours) before pushing.
+I'm intending to provide some rather more cooked way to do this but I
+haven't decided the exact shape yet.
==== data flow slide
DMs currently need to email me a signed copy of their ssh key, in
-order to be able to push. This is because the project doesn't, right
-now, have a record of DMs' ssh keys.
+order to be able to push. This is because the dgit repo server uses
+ssh as a transport and the project doesn't, right now, have a record
+of DMs' ssh keys.
The dgit git history does not generally include the package upload
Many packages have strangely-behaved or plain buggy clean targets.
Because dgit knows that your git tree is canonical, it can help work
-around this: you can tell dgit to use git clean instead, avoiding the
+around this: you can tell dgit to use git-clean instead, avoiding the
package's clean target entirely.
+If you're not in the habit of forgetting to say git-add, you can set a
+configuration option to have dgit always use git-clean. Then you will
+never have to fight a buggy clean target, in a strange package, again.
+
Some source packages contain files not in the maintainers' git
branches, and which are needed to build: most commonly, autotools
nor your source package need contain the autotools output and all is
well.
-Alternatively, you can commit the autotools output to git.
+Alternatively, you can commit the autotools output to git. Merge
+conflicts etc. are easily resolved by rerunning autotools.
==== Future plans slide
~ijackson / talk-2015-debconf-dgit.git / commitdiff