dgit-nmu-simple(7)

1dgit-nmu-simple(7)                   dgit                   dgit-nmu-simple(7)
2
3
4

NAME

6       dgit-nmu-simple - tutorial for DDs wanting to NMU with git
7

INTRODUCTION AND SCOPE

9       This tutorial describes how a Debian Developer can do a straightforward
10       NMU of a package in Debian, using dgit.
11
12       This document won't help you decide whether an NMU is a good idea or
13       whether it be well received.  The Debian Developers' Reference has some
14       (sometimes questionable) guidance on this.
15
16       Conversely, you do not need to know anything about the usual
17       maintainer's git workflow.  If appropriate, you can work on many
18       different packages, making similar changes, without worrying about the
19       individual maintainers' git practices.
20
21       This tutorial only covers changes which can sensibly be expressed as a
22       reasonably small number of linear commits (whether to Debian packaging
23       or to upstream files or both).
24
25       If you want to do a new upstream version, you probably want to do as
26       the maintainer would have done.  You'll need to find out what the
27       maintainer's git practices are and consult the appropriate
28       "dgit-maint-*(7)" workflow tutorial,
29

SUMMARY

31           % dgit clone glibc jessie
32           % cd glibc
33           % git am ~/glibc-security-fix.diff
34           % dch --nmu "Apply upstream's fix for foo bug."
35           % git add debian/changelog && git commit -m"NMU changelog entry"
36           % dpkg-buildpackage -uc -b
37           [ run your tests ]
38           % dch -r && git add debian/changelog && git commit -m"Finalise NMU"
39           % dgit -wgf sbuild -A -c jessie
40           [ any final tests on generated .debs ]
41           % dgit -wgf [--delayed=5] push-source jessie
42           [ enter your gnupg passphrase as prompted ]
43           [ see that push and upload are successful ]
44           [ prepare and email NMU diff (git-diff, git-format-patch) ]
45

WHAT KIND OF CHANGES AND COMMITS TO MAKE

47       When preparing an NMU, the git commits you make on the dgit branch
48       should be simple linear series of commits with good commit messages.
49       The commit messages will be published in various ways, including
50       perhaps being used as the cover messages for generated quilt patches.
51
52       Do not make merge commits.  Do not try to rebase to drop patches - if
53       you need to revert a change which is actually a Debian patch, use git-
54       revert.
55
56       If you need to modify a Debian patch, make a new commit which fixes
57       what needs fixing, and explain in the commit message which patch it
58       should be squashed with (perhaps by use of a commit message in "git
59       rebase --autosquash -i" format).
60
61       (Of course if you have specific instructions from the maintainer, you
62       can follow those instead.  But the procedure in this tutorial is
63       legitimate for any maintainer, in the sense that it should generate an
64       upload to which the maintainer cannot reasonably object.)
65

RELEVANT BRANCHES

67       dgit clone will put you on a branch like "dgit/sid".  There is a
68       pseudo-remote called "dgit" which also contains a branch like
69       "dgit/sid", so you do things like "git diff dgit/dgit/sid" to see what
70       changes you have made.
71

KEEPING YOUR WORKING TREE TIDY

73       Don't forget to "git add" any new files you create.  Otherwise git
74       clean (which is requested with the "-wgf" option in the recipe above)
75       will delete them.
76
77       Many package builds leave dirty git trees.  So, commit before building.
78       That way you can use "git reset --hard".
79
80       If you follow this approach you don't need to care about the build
81       dirtying the tree.  It also means you don't care about the package
82       clean target, which is just as well because many package clean targets
83       are broken.
84

OTHER GIT BRANCHES

86       The dgit git history (visible in gitk and git log) is not necessarily
87       related to the maintainer's or upstream's git history (if any).
88
89       If the maintainer has advertised a git repo with Vcs-Git dgit will set
90       up a remote for it, so you can do
91
92           % git fetch vcs-git
93
94       You can cherry pick changes from there, for example.  Note that the
95       maintainer's git history may not be suitable for use with dgit.  For
96       example, it might be a patches-unapplied branch or even contain only a
97       debian/ directory.
98

UPLOADING TO DELAYED

100       You can use dgit's --delayed option to upload to the DELAYED queue.
101       However, you should read the warning about this option in dgit(1).
102