From: Ian Jackson Date: Wed, 29 Jul 2015 20:25:39 +0000 (+0100) Subject: manpage-request, wip X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit-junk.git;a=commitdiff_plain;h=c34f18df111a1b59e7cadb60b7415889232398dd;hp=17ee7a97dfc83fe49ba58ceaf2d7836df18761a6 manpage-request, wip --- diff --git a/manpage-request b/manpage-request new file mode 100644 index 0000000..00b0543 --- /dev/null +++ b/manpage-request @@ -0,0 +1,163 @@ +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 ) 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 +