|author||Ian Jackson <firstname.lastname@example.org>||2016-10-30 23:56:29 +0000|
|committer||Ian Jackson <email@example.com>||2016-10-30 23:56:29 +0000|
Merge branch 'wip.tutorials' into wip
Diffstat (limited to 'dgit-nmu-simple.7.pod')
1 files changed, 143 insertions, 0 deletions
diff --git a/dgit-nmu-simple.7.pod b/dgit-nmu-simple.7.pod
new file mode 100644
@@ -0,0 +1,143 @@
+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 git 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
+consult the appropriate C<dgit-maint-*(7)> workflow tutorial,
+note that dgit cannot yet be used
+to upload to the DELAYED queues.
+ % dgit clone glibc jessie
+ % cd glibc
+ % git am ~/glibc-security-fix.diff
+ % dch --nmu "Apply upstream's fix for foo bug."
+ % git add debian/changelog && git commit -m"NMU changelog entry"
+ % dpkg-buildpackage -uc -b
+ [ run your tests ]
+ % dch -r && git add debian/changelog && git commit -m"Finalise NMU"
+ % dgit -wgf sbuild -A -c jessie
+ [ final tests on generated .debs ]
+ % dgit -wgf [--delayed=5] 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) ]
+=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,
+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
+(perhaps by use of a commit message in C<git rebase --autosquash -i>
+(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<dgit/sid>.
+There is a pseudo-remote called C<dgit> which also contains a branch
+like C<dgit/sid>, so you do things like
+C<git diff dgit/dgit/sid>
+to see what changes you have made.
+=head1 KEEPING YOUR WORKING TREE TIDY
+Don't forget to C<git add> 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<git reset --hard>.
+If you follow this approach
+you don't need to care about the build dirtying the
+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 OTHER GIT BRANCHES
+The dgit git history
+(visible in gitk and git log)
+is not necessarily related to the maintainer's
+or upstream's git history (if any).
+If the maintainer has advertised a git repo with
+dgit will set up a remote for it,
+so you can do
+ % git fetch vcs-git
+You can cherry pick changes from there, for example.
+Note that the maintainer's git history may not be
+suitable for use with dgit.
+For example, it might be a patches-unapplied branch
+or even contain only a debian/ directory.
+=head1 UPLOADING TO DELAYED
+You can use dgit's I<--delayed> option
+to upload to the DELAYED queue.
+However, you should read the warning about this option in dgit(1).
+=head1 SEE ALSO
+dgit(1), dgit(7), dgit-maint-*(7)