Package: git-dpm
Severity: wishlist
Version: 0.9.1-1
Hi. In this mail you'll find:
1. introduction
2. description of dgit's model as it might concern git-dpm
3. suggested structure and for a new manpage
4. some quirks and caveats
5. references
1. Introduction
You may have heard of dgit, which is a tool for sharing a canonical
git representation of Debian packages, and particularly, packages in
the Debian archive.
dgit is not a competitor to git-dpm. Indeed, dgit is intended to be
complementary to existing Debian git packaging tools. I think that
git-dpm can probably be used together with dgit, and it would be good
to help users make git-dpm and dgit to work well together.
It may also be that git-dpm and/or dgit should get some new feature(s) or
operation(s) to work better together.
Because I don't understand git-dpm very well I'm not sure of the
details. I'm hoping that you would like to write, or help me write,
documentation (perhaps a manpage git-dpm-dgit(7), which I could
cross-reference from dgit(1)).
Please let me know whether you think this is a good idea and whether
you're able to help. If you want to talk in person, and will be at
Debconf, find me in Heidelberg.
2. dgit's purpose and model
The point of dgit is to provide a standard location, and standard tree
layout, for contributors and users to share and find a git
representation of every package. Ideally, that git representation
would be the maintainer's representation - so, ideally, if the
maintainer is using git-dpm, it would be nice if they could use dgit
push to upload, and dgit fetch to integrate NMUs.
dgit mainly replaces `sign and dupload', and `debcheckout'. For each
package there is a fast-forwarding git branch (one per suite) on a
central dgit server.
The tree contents (in git terminology) of that branch correspond
precisely to the contents of the corresponding source package. (In
more detail: dgit records a `patches-applied packaging branch without
.pc directory'.)
The commit graph structure of the dgit branch is primarily up to the
maintainer. The only requirements imposed by dgit are that:
successive uploads are fast forwards; and, that NMUs are represented
by linear commit(s) on the tip of that branch.
When a maintainer is using dgit with git-dpm, it is git-dpm which
determines the commit structure, subject to these constraints.
3. Suggsted manpage skeleton
Here is a suggestion for what information is needed and how it might
be structured. Sorry that I don't have the knowledge to write
something more complete. (Below, XXX notes and comments in [ ] are
directed to you, the maintainer of git-dpm.)
If git-dpm or dgit need improvement, this ought to become obvious when
trying to finish up this manpage.
NAME
git-dpm-dgit(7) - use of dgit with git-dpm
SYNOPSIS
dgit can be used to publish and share the git history that git-dpm
works with. This dgit integration guide is for the git-dpm-using
maintainer.
PUSHING (UPLOADING) WITH DGIT
git-dpm's XXX [which branch?] branch is directly suitable for use
with dgit push.
After finalising development with
git-dpm MAKE-THE-RIGHT-THING-TO-UPLOAD
the binary and source package(s) should be built with
dgit sbuild
or
dgit build
Then dgit push can be used. See dgit(1) for details.
USING GIT-DPM WITH DGIT FOR THE FIRST TIME
dgit requires that each upload is a fast forward from the previous
one (even if the dgit view of the previous upload is a commit
synthesised by dgit).
So when switching to using git-dpm with dgit, it is necessary to
stitch the previous dgit history into the git branch:
1. Run dgit fetch (or dgit fetch <suite>) to get the dgit view of
the current archive state.
2. Check (for example by looking at debian/changelog in your own
branch, and comparing it to debian/changelog in dgit/sid) that
the version you are about to upload really is descended from
the last upload.
3. Run
git merge -s ours dgit/sid
to generate a `merge' commit which contains exactly your code
but which is also a descendant of the dgit history.
XXX [ Would it be better for there to be some more automatic way
to do tthis ? ]
When you next come to run git-dpm you will need to XXX [ Will
git-dpm work on such history or does thte maintainer need to do
something special ? ]
HANDLING AN NMU
An NMU should appear in the git history as some additional,
linear, commits, descended from the commit of your last upload.
To integrate these changes into your own XXX [ git history,
branch, whatever? ] you must XXX [ do what? ]
NMUs made with dgit will contain whatever git history the NMUer
pushed, which should be reasonably clean. (If not, complain to
the NMUer.)
SEE ALSO
dgit(1), dgit(7), ...
4. Quirks
The dgit view of an NMU may contain commits withh a mixture of
debian/ and upstream changes. The intermediate states in the dgit
git branch, between the last maintainer upload and the nmu, may
not necessarily have the corresponding updates to debian/patches.
NMUs not made with dgit will appear as a merge of 1. a root commit
describing the .dsc that was uploaded, and 2. a merge to stitch it
into the suite branch.
dgit's source packages and git trees contain .gitignore. Current
default behaviour for dpkg-buildpackage -I is to remove
.gitignore. This is not correct for dgit because the .dsc and git
tree must be identical. The main effect is just that it is best
to use of dgit's build wrapper operations to build the package,
since dgit knows the right -I options.
5. References
dgit(1) manpage
http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git-manpage/dgit.git/dgit.1
dgit(7) manpage
http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git-manpage/dgit.git/dgit.7
dgit 1.0 release announcement
https://lists.debian.org/debian-devel-announce/2015/07/msg00003.html
Thanks for your attention.
Regards,
Ian.
--
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
