chiark / gitweb /
git-workflows: apropos smcv comments
[dgit-junk.git] / manpage-request
1 Subject: request for manpage TOOL-dgit(7)
2
3 Severity: wishlist
4
5 Hi.  In this mail you'll find:
6
7  1. introduction
8  2. description of dgit's model as it might concern TOOL
9  3. suggested structure and for a new manpage
10  4. some quirks and caveats
11  5. references
12
13
14 1. Introduction
15
16 You may have heard of dgit, which is a tool for sharing a canonical
17 git representation of Debian packages, and particularly, packages in
18 the Debian archive.
19
20 dgit is not a competitor to TOOL.  Indeed, dgit is intended to be
21 complementary to existing Debian git packaging tools.  I think that
22 TOOL can probably be used together with dgit, and it would be good to
23 help users get TOOL and dgit to work well together.
24
25 It may also be that TOOL and/or dgit should get some new feature(s) or
26 operation(s) to work better together.
27
28 Because I don't understand TOOL very well I'm not sure of the details.
29 I'm hoping that you would like to write, or help me write, a manpage
30 TOOL-dgit(7) (which I could cross-reference from dgit(1)).
31
32 Please let me know whether you think this is a good idea and whether
33 you're able to help.
34
35
36 2. dgit's purpose and model
37
38 dgit mainly replaces `sign and dupload', and `debcheckout'.  For each
39 package there is a fast-forwarding git branch (one per suite) on a
40 central dgit server.
41
42 The tree contents (in git terminology) of that branch correspond
43 precisely to the contents of the corresponding source package.  (In
44 more detail: dgit records a `patches-applied packaging branch without
45 .pc directory'.)
46
47 The commit graph structure of the dgit branch is primarily up to the
48 maintainer.  The only requirements imposed by dgit are that:
49 successive uploads are fast forwards; and, that NMUs are represented
50 by linear commit(s) on the tip of that branch.
51
52 When a maintainer is using dgit with TOOL, it is TOOL which determines
53 the commit structure, subject to these constraints.
54
55
56 3. Suggsted manpage skeleton
57
58 Here is a suggestion for what information is needed and how it might
59 be structured.  Sorry that I don't have the knowledge to write
60 something more complete.  (Below, XXX notes and comments in [ ] are
61 directed to you, the maintainer of TOOL.)
62
63 If new TOOL or dgit need improvement, this ought to become obvious
64 when trying to write the manpage.
65
66
67 NAME
68     TOOL-dgit(7) - use of dgit with TOOL
69
70 SYNOPSIS
71
72     dgit can be used to publish and share the git history that TOOL
73     works with.  This dgit integration guide is for the TOOL-using
74     maintainer.
75
76 PUSHING (UPLOADING) WITH DGIT
77
78     TOOL's XXX [which branch?] branch is directly suitable for use
79     with dgit push.
80
81     After finalising development with
82        TOOL MAKE-THE-RIGHT-THING-TO-UPLOAD
83     the binary and source package(s) should be built with
84        dgit sbuild
85     or
86        dgit build
87
88     Then dgit push can be used.  See dgit(1) for details.
89
90 USING *TOOL* WITH DGIT FOR THE FIRST TIME
91
92     dgit requires that each upload is a fast forward from the previous
93     one (even if the dgit view of the previous upload is a commit
94     synthesised by dgit).
95
96     So when switching to using TOOL with dgit, it is necessary to
97     stitch the previous dgit history into the git branch:
98
99     1. Run dgit fetch (or dgit fetch <suite>) to get the dgit view
100        of the current archive state.
101
102     2. Check (for example by looking at debian/changelog in your own
103        branch, and comparing it to debian/changelog in dgit/sid) that
104        the version you are about to upload really is descended from
105        the last upload.
106
107     3. Run
108          git merge -s ours dgit/sid
109        to generate a `merge' commit which contains exactly your code
110        but which is also a descendant of the dgit history.
111
112     When you next come to run TOOL you will need to XXX [will TOOL
113     work on such history or does user need to do something special?]
114
115 HANDLING AN NMU
116
117     An NMU should appear in the git history as some additional,
118     linear, commits, descended from the commit of your last upload.
119
120     To integrate these changes into your own XXX [ git history,
121     branch, whatever? ] you must XXX [ do what? ]
122
123     NMUs made with dgit will contain whatever git history the NMUer
124     pushed, which should be reasonably clean.  (If not, complain to
125     the NMUer.)
126
127 SEE ALSO
128     dgit(1), dgit(7), ...
129
130     NMUers who 
131
132
133 4. Quirks
134
135     The dgit view of an NMU may contain commits withh a mixture of
136     debian/ and upstream changes.  The intermediate states in the dgit
137     git branch, between the last maintainer upload and the nmu, may
138     not necessarily have the corresponding updates to
139     debian/patches.
140
141     NMUs not made with dgit will appear as a merge of 1. a root commit
142     describing the .dsc that was uploaded, and 2. a merge to stitch it
143     into the suite branch.
144
145     dgit's source packages and git trees contain .gitignore.  Current
146     default behaviour for dpkg-buildpackage -I is to remove
147     .gitignore.  This is not correct for dgit because the .dsc and git
148     tree must be identical.  The main effect is just that it is best
149     to use of dgit's build wrapper operations to build the package,
150     since dgit knows the right -I options.
151
152
153 5. References
154
155  dgit(1) manpage
156  http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git-manpage/dgit.git/dgit.1
157
158  dgit(7) manpage
159  http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git-manpage/dgit.git/dgit.1
160
161  dgit 1.0 release announcement
162  https://lists.debian.org/debian-devel-announce/2015/07/msg00003.html
163