chiark / gitweb /
debian/changelog: Document dgit-maint-merge(7)
[dgit.git] / dgit-maint-merge.7.pod
1 =head1 NAME
2
3 dgit - tutorial for package maintainers, using a workflow centered around git-merge(1)
4
5 =head1 INTRODUCTION
6
7 This document describes elements of a workflow for maintaining a
8 non-native Debian package using B<dgit>.  The workflow makes the
9 following opinionated assumptions:
10
11 =over 4
12
13 =item
14
15 Git histories should be the non-linear histories produced by
16 git-merge(1), preserving all information about divergent development
17 that was later brought together.
18
19 If you prefer linear histories, see dgit-maint-rebase(7).
20
21 =item
22
23 Maintaining convenient and powerful git workflows takes priority over
24 the usefulness of the raw Debian source package.  The Debian archive
25 is thought of as an output format.
26
27 For example, we don't spend time curating a series of quilt patches.
28 However, the information such a series would contain is readily
29 available from B<dgit-repos>.
30
31 =item
32
33 It is more important to have the Debian package's git history be a
34 descendent of upstream's git history than to use exactly the orig.tar
35 that upstream makes available for download.
36
37 =back
38
39 =head1 GIT CONFIGURATION
40
41 Add the following to your ~/.gitconfig to teach git-archive(1) how to
42 compress orig tarballs:
43
44 =over 4
45
46     [tar "tar.xz"]
47         command = xz -c
48     [tar "tar.gz"]
49         command = gzip -c
50
51 =back
52
53 =head1 INITIAL DEBIANISATION
54
55 =head2 When upstream tags releases in git and releases identical tarballs
56
57 Ideally upstream would make git tags, and tarball releases, which are
58 completely identical to each other.  If this is the case then you can
59 use the upstream tarballs directly.
60
61 If you're not sure, use the procedure below under "When upstream
62 releases only tarballs" only with a different upstream tag name.  Then
63 use git diff to check that there are no differences.
64
65 =head2 When upstream tags releases in git
66
67 Suppose that the latest stable upstream release is 1.2.2, and this has
68 been tagged '1.2.2' by upstream.
69
70 =over 4
71
72     % git clone -oupstream https://some.upstream/foo.git
73     % cd foo
74     % git verify-tag 1.2.2
75     % git reset --hard 1.2.2
76     % git branch --unset-upstream
77
78 =back
79
80 The final command detachs your master branch from the upstream remote,
81 so that git doesn't try to push anything there, or merge unreleased
82 upstream commits.  If you want to maintain a copy of your packaging
83 branch on B<alioth.debian.org> in addition to B<dgit-repos>, you can
84 do something like this:
85
86 =over 4
87
88     % git remote add -f origin git.debian.org:/git/collab-maint/foo.git
89     % git push --follow-tags -u origin master
90
91 =back
92
93 Now go ahead and Debianise your package.  Just make commits on the
94 master branch, adding things in the I<debian/> directory.  If you need
95 to patch the upstream source, just make commits that change files
96 outside of the I<debian/> directory.  It is best to separate commits
97 that touch I<debian/> from commits that touch upstream source, so that
98 the latter can be cherry-picked by upstream.
99
100 Note that there is no need to maintain a separate 'upstream' branch,
101 unless you also happen to be involved in upstream development.  We
102 work with upstream tags rather than any branches, except when
103 forwarding patches (see FORWARDING PATCHES UPSTREAM, below).
104
105 Finally, you need an orig tarball.  Generate one with git-archive(1):
106
107 =over 4
108
109     % git archive -o ../foo_1.2.2.orig.tar.xz 1.2.2
110
111 =back
112
113 If you are using the version 1.0 source package format, replace 'xz'
114 with 'gz'.
115
116 This tarball is ephemeral and easily regenerated, so we don't commit
117 it anywhere (e.g. with tools like pristine-tar(1)).
118
119 =head2 When upstream releases only tarballs
120
121 We need a virtual upstream branch with virtual release tags.
122 gbp-import-orig(1) can manage this for us.  To begin
123
124 =over 4
125
126     % mkdir foo
127     % cd foo
128     % git init
129
130 =back
131
132 Now create I<debian/gbp.conf>:
133
134 =over 4
135
136     [DEFAULT]
137     upstream-branch = upstream
138     debian-branch = master
139     upstream-tag = %(version)s
140
141     sign-tags = True
142     pristine-tar = False
143     pristine-tar-commit = False
144
145 =back
146
147 Then we can import the upstream version:
148
149 =over 4
150
151     % git add debian/gbp.conf && git commit -m "create gbp.conf"
152     % gbp import-orig ../foo_1.2.2.orig.tar.xz
153
154 =back
155
156 You are now ready to proceed as above, making commits to both the
157 upstream source and the I<debian/> directory.
158
159 If you want to maintain a copy of your repository on
160 B<alioth.debian.org>, you should push both the origin and the upstream
161 branches:
162
163 =over 4
164
165     % git remote add -f origin git.debian.org:/git/collab-maint/foo.git
166     % git push --follow-tags -u origin master upstream
167
168 =back
169
170 =head1 SOURCE PACKAGE CONFIGURATION
171
172 =head2 debian/source/options
173
174 We set some source package options such that dgit can transparently
175 handle the "dropping" and "refreshing" of changes to the upstream
176 source:
177
178 =over 4
179
180     single-debian-patch
181     auto-commit
182
183 =back
184
185 You don't need to create this file if you are using the version 1.0
186 source package format.
187
188 =head2 Sample text for README.source
189
190 It is a good idea to explain how a user can obtain a break down of the
191 changes to the upstream source:
192
193 =over 4
194
195 The Debian packaging of foo is maintained using dgit.  For the sake of
196 an efficient workflow, Debian modifications to the upstream source are
197 squashed into a single patch, rather than a series of quilt patches.
198 To obtain a patch queue for package version 1.2.3-1:
199
200 =over 4
201
202     # apt-get install dgit
203     % dgit clone foo
204     % cd foo
205     % git log --oneline 1.2.3..debian/1.2.3-1 -- . ':!debian'
206
207 =back
208
209 See dgit(1), dgit(7) and dgit-maint-merge(7) for more information.
210
211 =back
212
213 =head1 BUILDING AND UPLOADING
214
215 Use B<dgit build>, B<dgit sbuild>, B<dgit build-source>, and B<dgit
216 push> as detailed in dgit(1).  If any command fails, dgit will provide
217 a carefully-worded error message explaining what you should do.  If
218 it's not clear, file a bug against dgit.  Remember to pass I<--new>
219 for the first upload.
220
221 As an alternative to B<dgit build> and friends, you can use a tool
222 like gitpkg(1).  This works because like dgit, gitpkg(1) enforces that
223 HEAD has exactly the contents of the source package.  gitpkg(1) is
224 highly configurable, and one dgit user reports using it to produce and
225 test multiple source packages, from different branches corresponding
226 to each of the current Debian suites.
227
228 If you want to skip dgit's checks while iterating on a problem with
229 the package build (for example, you don't want to commit your changes
230 to git), you can just run dpkg-buildpackage(1) or debuild(1) instead.
231
232 =head1 NEW UPSTREAM RELEASES
233
234 =head2 When upstream tags releases in git
235
236 It's a good idea to preview the merge of the new upstream release.
237 First, just check for any new or deleted files that may need
238 accounting for in your copyright file:
239
240 =over 4
241
242     % git remote update
243     % git diff --stat master..1.2.3 -- . ':!debian'
244
245 =back
246
247 You can then review the full merge diff:
248
249 =over 4
250
251     % git merge-tree `git merge-base master 1.2.3` master 1.2.3 | $PAGER
252
253 =back
254
255 Once you're satisfied with what will be merged, update your package:
256
257 =over 4
258
259     % git archive ../foo_1.2.3.orig.tar.xz 1.2.3
260     % git merge 1.2.3
261     % dch -v1.2.3-1 New upstream release.
262     % git add debian/changelog && git commit -m changelog
263
264 =back
265
266 and you are ready to try a build.
267
268 Again, if you are using the version 1.0 source package format, replace
269 'xz' with 'gz'.
270
271 =head2 When upstream releases only tarballs
272
273 Either
274
275 =over 4
276
277     % gbp import-orig ../foo_1.2.2.orig.tar.xz
278
279 =back
280
281 or if you have a working watch file
282
283 =over 4
284
285     % gbp import-orig --uscan
286
287 =back
288
289 =head1 HANDLING DFSG-NON-FREE MATERIAL
290
291 =head2 When upstream tags releases in git
292
293 We create a DFSG-clean tag to merge to master:
294
295 =over 4
296
297     % git checkout -b pre-dfsg 1.2.3
298     % git rm evil.bin
299     % git commit -m "upstream version 1.2.3 DFSG-cleaned"
300     % git tag -s 1.2.3+dfsg
301     % git checkout master
302     % git branch -D pre-dfsg
303
304 =back
305
306 Before merging the new 1.2.3+dfsg tag to master, you should first
307 determine whether it would be legally dangerous for the non-free
308 material to be publicly accessible in the git history on
309 B<dgit-repos>.
310 If it would be dangerous, there is a big problem;
311 in this case please consult your archive administrators
312 (for Debian this is the dgit administrator dgit-owner@debian.org
313 and the ftpmasters ftpmaster@ftp-master.debian.org).
314
315 =head2 When upstream releases only tarballs
316
317 The easiest way to handle this is to add a B<Files-Excluded> field to
318 I<debian/copyright>, and a B<uversionmangle> setting in
319 I<debian/watch>.  See uscan(1).  Alternatively, see the I<--filter>
320 option detailed in gbp-import-orig(1).
321
322 =head1 FORWARDING PATCHES UPSTREAM
323
324 The basic steps are:
325
326 =over 4
327
328 =item 1.
329
330 Create a new branch based off upstream's master branch.
331
332 =item 2.
333
334 git-cherry-pick(1) commits from your master branch onto your new
335 branch.
336
337 =item 3.
338
339 Push the branch somewhere and ask upstream to merge it, or use
340 git-format-patch(1) or git-request-pull(1).
341
342 =back
343
344 For example (and it is only an example):
345
346 =over 4
347
348     % # fork foo.git on GitHub
349     % git remote add -f fork git@github.com:spwhitton/foo.git
350     % git checkout -b fix-error upstream/master
351     % git config branch.fix-error.pushRemote fork
352     % git cherry-pick master^2
353     % git push
354     % # submit pull request on GitHub
355
356 =back
357
358 Note that when you merge an upstream release containing your forwarded
359 patches, git and dgit will transparently handle "dropping" the patches
360 that have been forwarded, "retaining" the ones that haven't.
361
362 =head1 INCORPORATING NMUS
363
364 =over 4
365
366     % dgit pull
367
368 =back
369
370 Alternatively, you can apply the NMU diff to your repository.  The
371 next push will then require I<--overwrite>.
372
373 =head1 SEE ALSO
374
375 dgit(1), dgit(7)
376
377 =head1 AUTHOR
378
379 This tutorial was written and is maintained by Sean Whitton <spwhitton@spwhitton.name>.  It contains contributions from other dgit contributors too - see the dgit copyright file.