chiark / gitweb /
dgit-maint-native(7): Soften warning about ugliness
[dgit.git] / dgit-nmu-simple.7.pod
1 =head1 NAME
2
3 dgit-nmu-simple - tutorial for DDs wanting to NMU with git
4
5 =head1 INTRODUCTION AND SCOPE
6
7 This tutorial describes how a Debian Developer can do
8 a straightforward NMU
9 of a package in Debian, using dgit.
10
11 This document won't help you decide whether
12 an NMU is a good idea or
13 whether it be well received.
14 The Debian Developers' Reference has some
15 (sometimes questionable) guidance on this.
16
17 Conversely, you do not need to know anything
18 about the usual maintainer's git workflow.
19 If appropriate, you can work on many different packages,
20 making similar changes,
21 without worrying about the individual maintainers' git practices.
22
23 This tutorial only covers changes which
24 can sensibly be expressed as a
25 reasonably small number of linear commits
26 (whether to Debian packaging or to upstream files or both).
27
28 If you want to do a new upstream version,
29 you probably want to do as the maintainer would have done.
30 You'll need to find out what the maintainer's
31 git practices are
32 and 
33 consult the appropriate C<dgit-maint-*(7)> workflow tutorial,
34
35 Further,
36 note that dgit cannot yet be used
37 to upload to the DELAYED queues.
38
39 =head1 SUMMARY
40
41 =over 4
42
43     % dgit clone glibc jessie
44     % cd glibc
45     % git am ~/glibc-security-fix.diff
46     % dch --nmu "Apply upstream's fix for foo bug."
47     % git add debian/changelog && git commit -m"NMU changelog entry"
48     % dpkg-buildpackage -uc -b
49     [ run your tests ]
50     % dch -r && git add debian/changelog && git commit -m"Finalise NMU"
51     % dgit -wgf sbuild -A -c jessie
52     [ final tests on generated .debs ]
53     % dgit -wgf [--delayed=5] push jessie
54     [ enter your gnupg passphrase as prompted ]
55     [ see that push and upload are successful ]
56     [ prepare and email NMU diff (git-diff, git-format-patch) ]
57
58 =back
59
60 =head1 WHAT KIND OF CHANGES AND COMMITS TO MAKE
61
62 When preparing an NMU, the git commits you make on the dgit branch
63 should be simple linear series of commmits with good commit messages.
64 The commit messages will be published in various ways,
65 including perhaps being used as the cover messages for
66 genrated quilt patches.
67
68 Do not make merge commits.
69 Do not try to rebase to drop patches - if you need to revert a
70 change which is actually a Debian patch,
71 use git-revert.
72
73 If you need to modify a Debian patch,
74 make a new commit which fixes what needs fixing,
75 and explain in the commit message which patch it should be
76 squashed with
77 (perhaps by use of a commit message in C<git rebase --autosquash -i>
78 format).
79
80 (Of course if you have specific instructions from the maintainer,
81 you can follow those instead.
82 But the procedure in this tutorial is legitimate for any maintainer,
83 in the sense that it should generate an upload to which the
84 maintainer cannot reasonably object.)
85
86 =head1 RELEVANT BRANCHES
87
88 dgit clone will put you on a branch like C<dgit/sid>.
89 There is a pseudo-remote called C<dgit> which also contains a branch
90 like C<dgit/sid>, so you do things like
91 C<git diff dgit/dgit/sid>
92 to see what changes you have made.
93
94 =head1 KEEPING YOUR WORKING TREE TIDY
95
96 Don't forget to C<git add> any new files you create.
97 Otherwise git clean
98 (which is requested with the C<-wgf> option in the recipe above)
99 will delete them.
100
101 Many package builds leave dirty git trees.
102 So, commit before building.
103 That way you can use C<git reset --hard>.
104
105 If you follow this approach
106 you don't need to care about the build dirtying the
107 tree.
108 It also means you don't care about the package clean target,
109 which is just as well because many package clean targets are broken.
110
111 =head1 OTHER GIT BRANCHES
112
113 The dgit git history
114 (visible in gitk and git log)
115 is not necessarily related to the maintainer's
116 or upstream's git history (if any).
117
118 If the maintainer has advertised a git repo with
119 Vcs-Git
120 dgit will set up a remote for it,
121 so you can do
122
123 =over 4
124
125     % git fetch vcs-git
126
127 =back
128
129 You can cherry pick changes from there, for example. 
130 Note that the maintainer's git history may not be
131 suitable for use with dgit.
132 For example, it might be a patches-unapplied branch
133 or even contain only a debian/ directory.
134
135 =head1 UPLOADING TO DELAYED
136
137 You can use dgit's I<--delayed> option
138 to upload to the DELAYED queue.
139 However, you should read the warning about this option in dgit(1).
140
141 =head1 SEE ALSO
142
143 dgit(1), dgit(7), dgit-maint-*(7)