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 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 =head1 SUMMARY
  36
  37 =over 4
  38
  39     % dgit clone glibc jessie
  40     % cd glibc
  41     % git am ~/glibc-security-fix.diff
  42     [ edit debian/changelog to introduce a ~ version, and commit it ]
  43     % dpkg-buildpackage -uc -b
  44     [ run your tests ]
  45     [ edit debian/changelog to prepare for release, and commit it ]
  46     % dgit -wgf sbuild -A -c jessie
  47     [ final tests on generated .debs ]
  48     % dgit -wgf push jessie
  49     [ enter your gnupg passphrase as prompted ]
  50     [ see that push and upload are successful ]
  51     [ prepare and email NMU diff (git-diff, git-format-patch) ]
  52
  53 =back
  54
  55 =head1 WHAT KIND OF CHANGES AND COMMITS TO MAKE
  56
  57 When preparing an NMU, the git commits you make on the dgit branch
  58 should be simple linear series of commmits with good commit messages.
  59 The commit messages will be published in various ways,
  60 including perhaps being used as the cover messages for
  61 genrated quilt patches.
  62
  63 Do not make merge commits.
  64 Do not try to rebase to drop patches - if you need to revert a
  65 change which is actually a Debian patch,
  66 use git-revert.
  67
  68 If you need to modify a Debian patch,
  69 make a new commit which fixes what needs fixing,
  70 and explain in the commit message which patch it should be
  71 squashed with
  72 (perhaps by use of a commit message in C<git rebase --autosquash -i>
  73 format).
  74
  75 (Of course if you have specific instructions from the maintainer,
  76 you can follow those instead.
  77 But the procedure in this tutorial is legitimate for any maintainer,
  78 in the sense that it should generate an upload to which the
  79 maintainer cannot reasonably object.)
  80
  81 =head1 RELEVANT BRANCHES
  82
  83 dgit clone will put you on a branch like C<dgit/sid>.
  84 There is a pseudo-remote called C<dgit> which also contains a branch
  85 like C<dgit/sid>, so you do things like
  86 C<git diff dgit/dgit/sid>
  87 to see what changes you have made.
  88
  89 =head1 KEEPING YOUR WORKING TREE TIDY
  90
  91 Don't forget to C<git add> any new files you create.
  92 Otherwise git clean
  93 (which is requested with the C<-wgf> option in the recipe above)
  94 will delete them.
  95
  96 Many package builds leave dirty git trees.
  97 So, commit before building.
  98 That way you can use C<git reset --hard>.
  99
 100 If you follow this approach
 101 you don't need to care about the build dirtying the
 102 tree.
 103 It also means you don't care about the package clean target,
 104 which is just as well because many package clean targets are broken.
 105
 106 =head1 SEE ALSO
 107
 108 dgit(1), dgit(7), dgit-maint-*(7)