From c4dea463ddc76cf7e39612dbdce3b18a5a0db957 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Thu, 27 Oct 2016 00:38:46 +0100 Subject: dgit-user(7), dgit-nmu-simple(7): Much work These are in reasonable shape now. Signed-off-by: Ian Jackson --- dgit-nmu-simple.7.pod | 108 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 dgit-nmu-simple.7.pod (limited to 'dgit-nmu-simple.7.pod') diff --git a/dgit-nmu-simple.7.pod b/dgit-nmu-simple.7.pod new file mode 100644 index 0000000..56b399a --- /dev/null +++ b/dgit-nmu-simple.7.pod @@ -0,0 +1,108 @@ +=head1 NAME + +dgit-nmu-simple - tutorial for DDs wanting to NMU with git + +=head1 INTRODUCTION AND SCOPE + +This tutorial describes how a Debian Developer can do +a straightforward NMU +of a package in Debian, using dgit. + +This document won't help you decide whether +an NMU is a good idea or +whether it be well received. +The Debian Developers' Reference has some +(sometimes questionable) guidance on this. + +Conversely, you do not need to know anything +about the usual maintainer's workflow. +If appropriate, you can work on many different packages, +making similar changes, +without worrying about the individual maintainers' git practices. + +This tutorial only covers changes which +can sensibly be expressed as a +reasonably small number of linear commits +(whether to Debian packaging or to upstream files or both). + +If you want to do a new upstream version, +you probably want to do as the maintainer would have done. +You'll need to find out what the maintainer's +git practices are +and +consult the appropriate C workflow tutorial, + +=head1 SUMMARY + +=over 4 + + % dgit clone glibc jessie + % cd glibc + % git am ~/glibc-security-fix.diff + [ edit debian/changelog to introduce a ~ version, and commit it ] + % dpkg-buildpackage -uc -b + [ run your tests ] + [ edit debian/changelog to prepare for release, and commit it ] + % dgit -wgf sbuild -A -c jessie + [ final tests on generated .debs ] + % dgit -wgf push jessie + [ enter your gnupg passphrase as prompted ] + [ see that push and upload are successful ] + [ prepare and email NMU diff (git-diff, git-format-patch) ] + +=back + +=head1 WHAT KIND OF CHANGES AND COMMITS TO MAKE + +When preparing an NMU, the git commits you make on the dgit branch +should be simple linear series of commmits with good commit messages. +The commit messages will be published in various ways, +including perhaps being used as the cover messages for +genrated quilt patches. + +Do not make merge commits. +Do not try to rebase to drop patches - if you need to revert a +change which is actually a Debian patch, +use git-revert. + +If you need to modify a Debian patch, +make a new commit which fixes what needs fixing, +and explain in the commit message which patch it should be +squashed with +(perhaps by use of a commit message in C +format). + +(Of course if you have specific instructions from the maintainer, +you can follow those instead. +But the procedure in this tutorial is legitimate for any maintainer, +in the sense that it should generate an upload to which the +maintainer cannot reasonably object.) + +=head1 RELEVANT BRANCHES + +dgit clone will put you on a branch like C. +There is a pseudo-remote called C which also contains a branch +like C, so you do things like +C +to see what changes you have made. + +=head1 KEEPING YOUR WORKING TREE TIDY + +Don't forget to C any new files you create. +Otherwise git clean +(which is requested with the C<-wgf> option in the recipe above) +will delete them. + +Many package builds leave dirty git trees. +So, commit before building. +That way you can use C. + +If you follow this approach +you don't need to care about the build dirtying the +tree. +It also means you don't care about the package clean target, +which is just as well because many package clean targets are broken. + +=head1 SEE ALSO + +dgit(1), dgit(7), dgit-maint-*(7) -- cgit v1.2.3