+Subject: request for manpage TOOL-dgit(7)
+
+Severity: wishlist
+
+Hi. In this mail you'll find:
+
+ 1. introduction
+ 2. description of dgit's model as it might concern TOOL
+ 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 TOOL. Indeed, dgit is intended to be
+complementary to existing Debian git packaging tools. I think that
+TOOL can probably be used together with dgit, and it would be good to
+help users get TOOL and dgit to work well together.
+
+It may also be that TOOL and/or dgit should get some new feature(s) or
+operation(s) to work better together.
+
+Because I don't understand TOOL very well I'm not sure of the details.
+I'm hoping that you would like to write, or help me write, a manpage
+TOOL-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.
+
+
+2. dgit's purpose and model
+
+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 needs 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 TOOL and dgit, it is TOOL which determines
+the commit structure, subject to the constraints above.
+
+
+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 TOOL.)
+
+If new TOOL or dgit need improvement, this ought to become obvious
+when trying to write the manpage.
+
+
+NAME
+ TOOL-dgit(7) - use of dgit with TOOL
+
+SYNOPSIS
+
+ dgit can be used to publish and share the git history that TOOL
+ works with. This dgit integration guide is for the TOOL-using
+ maintainer.
+
+PUSHING (UPLOADING) WITH DGIT
+
+ TOOL's XXX [which branch?] branch is directly suitable for use
+ with dgit push.
+
+ After finalising development with
+ TOOL 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 *TOOL* 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 TOOL 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.
+
+ When you next come to run TOOL you will need to XXX [will TOOL
+ work on such history or does user 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), ...
+
+ NMUers who
+
+
+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.1
+
+ dgit 1.0 release announcement
+ https://lists.debian.org/debian-devel-announce/2015/07/msg00003.html
+
~ianmdlvl / dgit-junk.git / commitdiff