chiark / gitweb /
Merge branch 'wip.tutorials' into wip
authorIan Jackson <ijackson@chiark.greenend.org.uk>
Sun, 30 Oct 2016 23:56:29 +0000 (23:56 +0000)
committerIan Jackson <ijackson@chiark.greenend.org.uk>
Sun, 30 Oct 2016 23:56:29 +0000 (23:56 +0000)
.gitignore
Makefile
debian/changelog
dgit-maint-gbp.7.pod [new file with mode: 0644]
dgit-maint-native.7.pod [new file with mode: 0644]
dgit-nmu-simple.7.pod [new file with mode: 0644]
dgit-sponsorship.7.pod [new file with mode: 0644]
dgit-user.7.pod [new file with mode: 0644]
dgit.1
dgit.7
local-pod-man [new file with mode: 0755]

index 69c2fea..13e2c4b 100644 (file)
@@ -6,5 +6,10 @@ debian/files
 debian/*.substvars
 debian/*.log
 debian/debhelper-build-stamp
+dgit-user.7
+dgit-nmu-simple.7
+dgit-maint-native.7
 dgit-maint-merge.7
+dgit-maint-gbp.7
+dgit-sponsorship.7
 substituted
index 9491e4d..68c1a02 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -34,7 +34,13 @@ absurddir=$(prefix)/share/dgit/absurd
 
 PROGRAMS=dgit
 MAN1PAGES=dgit.1
-MAN7PAGES=dgit.7 dgit-maint-merge.7
+
+MAN7PAGES=dgit.7                               \
+       dgit-user.7 dgit-nmu-simple.7           \
+       dgit-maint-native.7                     \
+       dgit-maint-merge.7 dgit-maint-gbp.7     \
+       dgit-sponsorship.7
+
 TXTDOCS=README.dsc-import
 PERLMODULES=Debian/Dgit.pm
 ABSURDITIES=git
index f945a3f..a67a205 100644 (file)
@@ -26,6 +26,12 @@ dgit (2.9~) unstable; urgency=low
     like testing.  Closes:#842621.
   * Properly fetch all archive dgit view tags, as we intended.
   * Actually provide a -p (--package=) option (!)
+  * dgit-*(7).  Many new tutorial manpages, several written and many
+    improved by Sean Whitton.
+  * dgit(7): Substantial updates, including documenting split view.
+  * dgit(1): Better cross-references.
+  * dgit(1): Remove obsolete workflow information.
+  * dgit(1): Improved BUGS section.
 
  --
 
diff --git a/dgit-maint-gbp.7.pod b/dgit-maint-gbp.7.pod
new file mode 100644 (file)
index 0000000..134593c
--- /dev/null
@@ -0,0 +1,130 @@
+=head1 NAME
+
+dgit - tutorial for package maintainers already using git-buildpackage(1)
+
+=head1 INTRODUCTION
+
+This document explains how B<dgit> can be incorporated into a
+git-buildpackage(1) package-maintenance workflow.  This should be read
+jointly with git-buildpackage(1)'s documentation.  Some reasons why
+you might want to incorporate B<dgit> into your existing workflow:
+
+=over 4
+
+=item
+
+Benefit from dgit's safety catches.  In particular, ensure that your
+upload always matches exactly your git HEAD.
+
+=item
+
+Provide a better, more detailed git history to downstream dgit users,
+such as people using dgit to do an NMU (see dgit-nmu-simple(7) and
+dgit-user(7)).
+
+=back
+
+Note that we assume a patches-unapplied repository: the upstream
+source committed to the git repository is unpatched.
+git-buildpackage(1) can work with patched-applied repositories, but is
+normally used with patches-unapplied.
+
+=head1 GIT CONFIGURATION
+
+If you run
+
+=over 4
+
+    % git config dgit.default.quilt-mode gbp
+
+=back
+
+in your repository, you can omit I<--gbp> wherever it occurs below.
+
+Note that this does require that you always work from your gbp master
+branch, never the dgit patches-applied branch.
+
+=head1 BUILDING
+
+If you use gbp-buildpackage(1) to generate your orig tarballs, you
+will need to perform the first build with gbp-buildpackage(1) directly
+(this is due to Debian bug #841084).
+
+Otherwise, you can perform builds like this:
+
+=over 4
+
+    % dgit [--allow-dirty] gbp-build [OPTIONS]
+
+=back
+
+where I<--allow-dirty> is needed for testing uncommitted changes, and
+I<OPTIONS> are any further options to be passed on to
+gbp-buildpackage(1).
+
+When you are ready to build for upload, you will probably want to use
+sbuild(1) or pbuilder(1), or do a source-only upload.  Either
+
+=over 4
+
+    % dgit --rm-old-changes --gbp sbuild
+
+=back
+
+or
+
+=over 4
+
+    % dgit --rm-old-changes gbp-build --git-pbuilder
+
+=back
+
+or
+
+=over 4
+
+    % dgit --rm-old-changes --gbp build-source
+
+=back
+
+We use I<--rm-old-changes> to ensure that there is exactly one changes
+file corresponding to this package, so we can be confident we're
+uploading what we intend (though B<dgit push> will do some safety
+checks).
+
+Note that all of the commands in this section are not required to
+upload with dgit.  You can invoke gbp-buildpackage(1), pbuilder(1) and
+sbuild(1) directly.  However, the defaults for these tools may leave
+you with something that dgit will refuse to upload because it doesn't
+match your git HEAD.  As a general rule, leave all signing and tagging
+to dgit.
+
+=head1 UPLOADING
+
+Don't use I<--git-tag>: B<dgit push> will do this for you.  To upload:
+
+=over 4
+
+    % dgit --gbp push
+
+=back
+
+This will push your git history to the dgit-repos, but you probably
+want to follow it up with a push to alioth.
+
+You will need to pass I<--overwrite> if the previous upload was not
+performed with dgit.
+
+=head1 INCORPORATING NMUS
+
+B<dgit pull> can't yet incorporate NMUs into patches-unapplied gbp
+branches.  You can just apply the NMU diff the traditional way.  The
+next upload will require I<--overwrite>.
+
+=head1 SEE ALSO
+
+dgit(1), dgit(7)
+
+=head1 AUTHOR
+
+This tutorial was written and is maintained by Sean Whitton <spwhitton@spwhitton.name>.
diff --git a/dgit-maint-native.7.pod b/dgit-maint-native.7.pod
new file mode 100644 (file)
index 0000000..5440759
--- /dev/null
@@ -0,0 +1,115 @@
+=head1 NAME
+
+dgit - tutorial for package maintainers of Debian-native packages
+
+=head1 INTRODUCTION
+
+This document describes elements of a workflow for maintaining a
+native Debian package using B<dgit>.
+
+=over 4
+
+=item
+
+We expect that your git history is fast-forwarding.
+
+=item
+
+You should be prepared to tolerate a small amount of
+ugliness in your git history
+in the form of merges which stitch
+the dgit-generated archive view
+into your maintainer history.
+
+This is to handle uploads that were not made with dgit,
+such as the uploads you made before switching to this workflow,
+or NMUs.
+
+=back
+
+=head2 Benefits
+
+=over 4
+
+=item
+
+Benefit from dgit's safety catches.  In particular, ensure that your
+upload always matches exactly your git HEAD.
+
+=item
+
+Provide a better,
+more detailed history
+to downstream dgit users.
+
+=item
+
+Incorporate an NMU with one command.
+
+=back
+
+=head1 FIRST PUSH WITH DGIT
+
+You do not need to do anything special to your tree
+to push with dgit.
+
+Simply prepare your git tree in the usual way, and then:
+
+=over 4
+
+    % dgit -wgf sbuild -A -c sid
+    % dgit -wgf --overwrite push
+
+=back
+
+(Do not make any tags yourself: dgit push will do that.)
+
+The --overwrite option tells dgit that you are expecting
+that your git history is not a descendant of the
+history which dgit synthesised from the previous
+non-dgit uploads.
+
+dgit will make a merge commit
+on your branch
+but without making any code changes
+(ie, a pseudo-merge)
+so that your history,
+which will be pushed to the dgit git server,
+is fast forward from the dgit archive view.
+
+=head1 SUBSEQUENT PUSHES
+
+=over 4
+
+    % dgit -wgf push
+
+=back
+
+That's it.
+
+=head1 INCORPORATING AN NMU
+
+=over 4
+
+    % dgit pull
+
+=back
+
+That's it.
+
+Or, if you would prefer to review the changes,
+you can do this:
+
+=over 4
+
+    % dgit fetch
+    % dgit diff HEAD..dgit/dgit/sid
+
+=back
+
+If you do not merge the NMU into your own git history,
+the next push will then require I<--overwrite>.
+
+=head1 SEE ALSO
+
+dgit(1), dgit(7)
diff --git a/dgit-nmu-simple.7.pod b/dgit-nmu-simple.7.pod
new file mode 100644 (file)
index 0000000..b30934f
--- /dev/null
@@ -0,0 +1,143 @@
+=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 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
+and 
+consult the appropriate C<dgit-maint-*(7)> workflow tutorial,
+
+Further,
+note that dgit cannot yet be used
+to upload to the DELAYED queues.
+
+=head1 SUMMARY
+
+=over 4
+
+    % 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) ]
+
+=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<git rebase --autosquash -i>
+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<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
+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 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
+Vcs-Git
+dgit will set up a remote for it,
+so you can do
+
+=over 4
+
+    % git fetch vcs-git
+
+=back
+
+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)
diff --git a/dgit-sponsorship.7.pod b/dgit-sponsorship.7.pod
new file mode 100644 (file)
index 0000000..8feb0d1
--- /dev/null
@@ -0,0 +1,297 @@
+=head1 NAME
+
+dgit-sponsorship - tutorial for Debian upload sponsorship, using git
+
+=head1 INTRODUCTION AND SCOPE
+
+This tutorial describes how a Debian sponsored contributor
+and
+a sponsoring DD (or DM)
+can collaborate and publish using git.
+
+The sponsor must to be intending to use dgit for the upload.
+(If the sponsor does not use dgit,
+it is not possible to properly publish
+a sponsee's git branch.)
+
+It is best if the sponsee also uses dgit;
+but also covered (later on) is the case where
+the sponsee provides a proposed upload in source package form,
+but the sponsor would like to work in git.
+
+This tutorial does not provide a checklist for the sponsor's review.
+Both contributors are expected to be familiar with Debian
+packaging and Debian's processes, and with git.
+
+=head1 SPONSEE WORKFLOW
+
+This section is addressed to the sponsee:
+
+=head2 General
+
+You should prepare the package as if you were going
+to upload it with C<dgit push> yourself.
+
+For a straightforward NMU, consult L<dgit-nmu-simple(7)>.
+
+If you are the (prospective) maintainer,
+you can adopt any suitable (dgit-compatible)
+git workflow.
+The L<dgit-maint-*(7)> tutorials describe some of the possibilities.
+
+=head2 Upload preparation
+
+You should go through all of the steps 
+a self-uploading maintainer would do,
+including building for ad hoc tests,
+and checking via a formal build (eg using C<dgit sbuild>)
+that the package builds on sid (or the target release).
+
+At the point where you would,
+if you were a DD, 
+do the actual upload
+by running dgit push,
+you hand off to your sponsor.
+
+If you were going to use one of the
+C<--quilt=>
+options to dgit, or
+C<dgit --gbp> or C<dgit --dpm>,
+you must specify that in your handoff email - see below.
+
+=head2 git+origs based handoff
+
+The elements of the handoff consists of:
+
+=over
+
+=item *
+
+The git branch.
+
+=item *
+
+Any .orig tarballs which will be needed.
+
+=item *
+
+A sample dgit push command, containing
+any dgit --quilt=, --gbp or --dpm option needed
+
+=item *
+
+Plus of course all the usual information about the state
+of the package,
+any caveats or areas you would like the sponsor to focus their review,
+constraints about upload timing, etc.
+
+=back
+
+If the handoff is done by email,
+the elements above should be a in a single, signed, message.
+This could be an RFS submission
+against the sponsorship-requests pseudo-package.
+
+=head3 git branch
+
+=over 4
+
+The sponsee should push their HEAD as a git branch
+to any suitable git server.
+They can use their own git server;
+alioth is another possibility.
+
+The branch names used by the sponsee on their local machine,
+and on the server, do not matter.
+
+The sponsee should not make a C<debian/>I<version> tag.
+
+Instead, the sponsee should include the
+git commit id of their HEAD
+in their handover email.
+
+=back
+
+=head3 orig tarballs
+
+=over 4
+
+If there are any .origs that are not in the archive already,
+the sponsor will need them as part of the upload.
+
+The simplest approach is to
+commit them with pristine-tar(1), e.g.
+
+=over 4
+
+    % pristine-tar commit ../foo_1.2.3.orig.tar.xz upstream/1.2.3
+
+=back
+
+and be sure to push the pristine-tar branch.
+If you are using git-buildpackage(1), just pass
+I<--git-pristine-tar> and I<--git-pristine-tar-commit>.
+
+Alternatively,
+the sponsee can put them on a suitable webserver,
+or attach to the e-mail,
+if they are small.
+
+The sponsee should quote sha256sums of the .origs in their
+handoff email.
+
+=back
+
+=head3 quilt options
+
+=over 4
+
+Some workflows involve git branches which are not natively
+dgit-compatible.
+Normally dgit will convert them as needed, during push.
+
+Supply a sample "dgit push" command
+including any
+C<--gbp> (aka C<--quilt=gbp>),
+C<--dpm> (aka C<--quilt=dpm>),
+or other C<--quilt=> option
+they need to use.
+e.g.
+
+=over 4
+
+    % dgit --gbp push
+
+=back
+
+=back
+
+=head1 SPONSOR WORKFLOW
+
+This part is addressed to the sponsor:
+
+=head2 Receiving and validating the sponsorship request
+
+You should check the signature on the email.
+
+Use C<git fetch> or C<git clone> to obtain the git branch
+prepared by your sponsee,
+and obtain any .origs mentioned by the sponsee
+(to extract .origs committed with pristine-tar,
+you can use origtargz(1),
+or use "gbp clone --pristine-tar".)
+
+Check the git commit ID of the sponsee's branch tip,
+and the sha256sums of the .origs,
+against the handoff email.
+
+Confirm that the sponsee has not made
+a debian/1.2.3-1 tag.
+If they have,
+it is best to ask them to delete it now,
+as it can cause confusion later when dgit push produces its own tag.
+
+Now you can check out the branch tip,
+and do your substantive review.
+
+=head2 Dealing with branches that want --quilt=
+
+If your sponsee mentioned a C<--quilt>
+option, and you don't want to grapple with their preferred tree format,
+you can convert their tree into the standard dgit view:
+
+=over 4
+
+    % dgit -wgf --quilt=foo --dgit-view-save=unquilted quilt-fixup
+    % git checkout unquilted
+
+=back
+
+You should check that what you're looking at is a descendant of
+the sponsee's branch.
+
+=head2 Some hints which may help the review
+
+C<dgit fetch sid> will get you an up-to-date
+C<refs/remotes/dgit/dgit/sid>
+showing what's in the archive already.
+
+C<dgit -wgf --damp-run push>
+will check that dgit can build an appropriate source package.
+
+There is no need to run debdiff.
+dgit will not upload anything that doesn't unpack
+to exactly the git commit you are pushing,
+so you can rely on what you see in C<git diff>.
+
+=head2 Doing the upload
+
+When you have completed your source review,
+and use
+C<dgit -wgf [--quilt=...] sbuild -A -C>
+or similar, to to the build, and then
+C<dgit -wgf [--quilt=...] push>
+to do the upload.
+
+(If you switched to the quilt-cache dgit view,
+B<do not> pass the --quilt or --gbp or --dpm option again.)
+
+If this was the first upload done with dgit,
+you may need to pass
+C<--overwrite>
+to dgit.
+
+
+=head1 SPONSORING A NON-GIT-USING SPONSEE
+
+This part is addressed to the sponsor:
+
+If your sponsee does not use git,
+you can still do your review with git,
+and use dgit for the upload.
+
+Your sponsee will provide you with a source package:
+that is, a .dsc and the files it refers to.
+Obtain these files, and check signatures as appropriate.
+Then:
+
+=over 4
+
+    % dgit clone PACKAGE
+    % cd PACKAGE
+    % dgit import-dsc /path/to/sponsee's.dsc +sponsee
+    % git checkout sponsee
+
+=back
+
+Or for an entirely new package:
+
+=over 4
+
+    % mkdir PACKAGE
+    % cd PACKAGE
+    % git init
+    % dgit -pPACKAGE import-dsc /path/to/sponsee's.dsc +sponsee
+
+=back
+
+This will leave you looking at the sponsee's package,
+formatted as a dgit branch.
+
+When you have finished your review and your tests,
+you can do the
+dgit sbuild and
+dgit push directly from the "sponsee" branch.
+
+You will need to pass
+C<--overwrite>
+to dgit push for every successive upload.
+This disables a safety catch which would normally spot
+situations where changes are accidentally lost.
+When your sponsee is sending you source packages -
+perhaps multiple source pacakges with the same version number -
+these safety catches are inevitably ineffective.
+
+=head1 SEE ALSO
+
+dgit(1), dgit(7), dgit-nmu-simple(7), dgit-maint-*(7)
diff --git a/dgit-user.7.pod b/dgit-user.7.pod
new file mode 100644 (file)
index 0000000..e730052
--- /dev/null
@@ -0,0 +1,415 @@
+=head1 NAME
+
+dgit-user - making and sharing changes to Debian packages, with git
+
+=head1 INTRODUCTION
+
+dgit lets you fetch the source code to every package on your
+system
+as if your distro used git to maintain all of it.
+
+You can then edit it,
+build updated binary packages (.debs)
+and install and run them.
+You can also share your work with others.
+
+This tutorial gives some recipes and hints for this.
+It assumes you have basic familiarity with git.
+It does not assume any initial familiarity with
+Debian's packaging processes.
+
+If you are a package maintainer within Debian; a DM or DD;
+and/or a sponsee:
+this tutorial is not for you.
+Try L<dgit-nmu-simple(7)>, L<dgit-maint-*(7)>,
+or L<dgit(1)> and L<dgit(7)>.
+
+=head1 SUMMARY
+
+(These runes will be discussed later.)
+
+=over 4
+
+    % dgit clone glibc jessie
+    % cd glibc
+    % wget 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u
+    % git commit -a -m 'Fix libc lost output bug'
+    % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
+    % sudo apt-get build-dep glibc
+    % dpkg-buildpackage -uc -b
+    % sudo dpkg -i ../libc6_*.deb
+
+=back
+
+Occasionally:
+
+=over 4
+
+    % git clean -xdf
+    % git reset --hard
+
+=back
+
+Later:
+
+=over 4
+
+    % cd glibc
+    % dgit pull jessie
+    % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
+    % dpkg-buildpackage -uc -b
+    % sudo dpkg -i ../libc6_*.deb
+
+=back
+
+=head1 FINDING THE RIGHT SOURCE CODE - DGIT CLONE
+
+=over 4
+
+    % dgit clone glibc jessie
+    % cd glibc
+
+=back
+
+dgit clone needs to be told the source package name
+(which might be different to the binary package name,
+which was the name you passed to "apt-get install")
+and the codename or alias of the Debian release
+(this is called the "suite").
+
+=head2 Finding the source package name
+
+For many packages, the source package name is obvious.
+Otherwise, if you know a file that's in the package,
+you can look it up with dpkg:
+
+=over 4
+
+    % dpkg -S /lib/i386-linux-gnu/libc.so.6 
+    libc6:i386: /lib/i386-linux-gnu/libc.so.6
+    % dpkg -s libc6:i386
+    Package: libc6
+    Status: install ok installed
+    ...
+    Source: glibc
+
+=back
+
+(In this example,
+libc6 is a "multi-arch: allowed" package,
+ which means that it exists in several different builds
+ for different architectures.
+That's where C<:i386> comes from.)
+
+=head2 Finding the Debian release (the "suite")
+
+Internally,
+Debian (and derived) distros normally refer to their releases by codenames.
+Debian also has aliases which refer to the current stable release etc.
+So for example, at the time of writing
+Debian C<jessie> (Debian 8) is Debian C<stable>; and
+the current version of Ubuntu is C<yakkety> (Yakkety Yak, 16.10).
+You can specify either
+the codename C<jessie> or the alias C<stable>.
+If you don't say, you get C<sid>,
+which is Debian C<unstable> - the main work-in progress branch.
+
+If you don't know what you're running, try this:
+
+=over 4
+
+    % grep '^deb' /etc/apt/sources.list
+    deb http://the.earth.li/debian/ jessie main non-free contrib
+    ...
+    %
+
+=back
+
+=head1 WHAT DGIT CLONE PRODUCES
+
+=head2 What branches are there
+
+dgit clone will give you a new working tree,
+and arrange for you to be on a branch like
+C<dgit/jessie>.
+
+There is a tracking branch for the contents of the archive, called
+C<remotes/dgit/dgit/jessie>
+(and similarly for other suites).  This can be updated with
+C<dgit fetch jessie>.
+This, the I<remote suite branch>,
+is synthesized by your local copy of dgit.
+It is fast forwarding.
+
+(You can also dgit fetch in a tree that wasn't made by dgit clone.
+If there's no C<debian/changelog>
+you'll have to supply a C<-p>I<package> option to dgit fetch.)
+
+=head2 What kind of source tree do you get
+
+If the Debian package is based on some upstream release,
+the code layout should be like the upstream version.
+You should find C<git grep> helpful to find where to edit.
+
+The package's Debian metadata and the scripts for building binary
+packages are under C<debian/>.
+C<debian/control>, C<debian/changelog> and C<debian/rules> are the
+starting points.
+The Debian Policy Manual has most of the in-depth
+technical details.
+
+For many Debian packages,
+there will also be some things in C<debian/patches/>.
+It is best to ignore these.
+Insofar as they are relevant
+the changes there will have been applied to the actual files,
+probably by means of actual comments in the git history.
+The contents of debian/patches are ignored
+when building binaries
+from dgitish git branches.
+
+(For Debian afficionados:
+the git trees that come out of dgit are
+"patches-applied packaging branches
+without a .pc directory".)
+
+=head2 What kind of history you get
+
+If you're lucky, the history will be a version of,
+or based on,
+the Debian maintainer's own git history,
+or upstream's git history.
+
+But for many packages the real git history
+does not exist,
+or has not been published in a dgitish form.
+So yuu may find that the history is a rather short
+history invented by dgit.
+
+dgit histories often contain automatically-generated commits,
+including commits which make no changes but just serve
+to make a rebasing branch fast-forward.
+
+If the package maintainer is using git then
+after dgit clone
+you may find that there is a useful C<vcs-git> remote
+referring to the Debian package maintainer's repository
+for the package.
+You can see what's there with C<git fetch vcs-git>.
+But use what you find there with care:
+Debian maintainers' git repositories often have
+contents which are very confusing and idiosyncratic.
+In particular, you may need to manually apply the patches
+that are in debian/patches before you do anything else!
+
+=head1 BUILDING
+
+=head2 Always commit before building
+
+=over 4
+
+    % wget 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u
+    % git commit -a -m 'Fix libc lost output bug'
+
+=back
+
+Debian package builds are often quite messy:
+they may modify files which are also committed to git,
+or leave outputs and teporary files not covered by C<.gitignore>.
+
+Kf you always commit,
+you can use
+
+=over 4
+
+    % git clean -xdf
+    % git reset --hard
+
+=back
+
+to tidy up after a build.
+(If you forgot to commit, don't use those commands;
+instead, you may find that you can use C<git add -p>
+to help commit what you actually wanted to keep.)
+
+These are destructive commands which delete all new files
+(so you B<must> remember to say C<git add>)
+and throw away edits to every file
+(so you B<must> remember to commit).
+
+=head2 Update the changelog (at least once) before building
+
+=over 4
+
+    % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
+
+=back
+
+The binaries you build will have a version number which ultimately
+comes from the C<debian/changelog>.
+You want to be able to tell your
+binaries apart from your distro's.
+
+So you should update C<debian/changelog>
+to add a new stanza at the top,
+for your build.
+
+This rune provides an easy way to do this.
+It adds a new changelog
+entry with an uninformative message and a plausible version number
+(containing a bit of your git commit id).
+
+If you want to be more sophisticated,
+the package C<dpkg-dev-el> has a good Emacs mode
+for editing changelogs.
+Alternatively, you could edit the changelog with another text editor,
+or run C<dch> or C<gbp dch> with different options.
+Choosing a good version number is slightly tricky and
+a complete treatment is beyond the scope of this tutorial.
+
+=head2 Actually building
+
+=over 4
+
+    % sudo apt-get build-dep glibc
+    % dpkg-buildpackage -uc -b
+
+=back
+
+apt-get build-dep installs the build dependencies according to the
+official package, not your modified one.  So if you've changed the
+build dependencies you might have to install some of them by hand.
+
+dpkg-buildpackage is the primary tool for building a Debian source
+package.
+C<-uc> means not to pgp-sign the results.
+C<-b> means build all binary packages,
+but not to build a source package.
+
+=head1 INSTALLING
+
+=head2 Debian Jessie or older
+
+=over 4
+
+    % sudo dpkg -i ../libc6_*.deb
+
+=back
+
+You can use C<dpkg -i> to install the
+.debs that came out of your package.
+
+If the dependencies aren't installed,
+you will get an error, which can usually be fixed with
+C<apt-get -f install>.
+
+=head2 Debian Stretch or newer
+
+=over 4
+
+    % sudo apt install ../libc6_*.deb
+
+=back
+
+=head1 Multiarch
+
+If you're working on a library package and your system has multiple
+architectures enabled,
+you may see something like this:
+
+=over 4
+
+    dpkg: error processing package libpcre3-dev:amd64 (--configure):
+     package libpcre3-dev:amd64 2:8.39-3~3.gbp8f25f5 cannot be configured because libpcre3-dev:i386 is at a different version (2:8.39-2)
+
+=back
+
+The multiarch system used by Debian requires each package which is
+present for multiple architectures to be exactly the same across
+all the architectures for which it is installed.
+
+The proper solution
+is to build the package for all the architectures you
+have enabled.
+You'll need a chroot for each of the secondary architectures.
+This iw somewhat tiresome,
+even though Debian has excellent tools for managing chroots.
+C<sbuild-createchroot> from the sbuild package is a
+good starting point.
+
+Otherwise you could deinstall the packages of interest
+for those other architectures
+with something like C<dpkg --remove libpcre3:i386>.
+
+If neither of those are an option,
+your desperate last resort is to try
+using the same version number
+as the official package for your own package.
+(The verseion is controlled by C<debian/changelog> - see above,)
+This is not ideal because it makes it hard to tell what is installed,
+because it will mislead and confuse apt.
+
+With the "same number" approach you may still get errors like
+
+=over 4
+
+trying to overwrite shared '/usr/include/pcreposix.h', which is different from other instances of package libpcre3-dev
+
+=back
+
+but passing C<--force-overwrite> to dpkg will help
+- assuming you know what you're doing.
+
+=head1 SHARING YOUR WORK
+
+The C<dgit/jessie> branch (or whatever) is a normal git branch.
+You can use C<git push> to publish it on any suitable git server.
+
+Anyone who gets that git branch from you
+will be able to build binary packages (.deb)
+just as you did.
+
+If you want to contribute your changes back to Debian,
+you should probably send them as attachments to 
+an email to the
+L<Debian Bug System|https://bugs.debian.org/>
+(either a followup to an existing bug, or a new bug).
+Patches in C<git-format-patch> format are usually very welcome.
+
+=head2 Source packages
+
+The
+git branch is not sufficient to build a source package
+the way Debian does.
+Source packages are somewhat awkward to work with.
+Indeed many plausible git histories or git trees
+cannot be converted into a suitable source package.
+So I recommend you share your git branch instead.
+
+If a git branch is not enough, and
+you need to provide a source package
+but don't care about its format/layout
+(for example because some software you have consumes source packages,
+not git histories)
+you can use this recipe to generate a C<1.0> "native"
+source package, which is just a tarball
+with accompanying .dsc metadata file:
+
+=over 4
+
+    % git rm debian/source/version
+    % git commit -m 'switch to 1.0 source format'
+    % dgit -wgf --dpkg-buildpackage:-sn build-source
+
+=back
+
+If you need to provide a good-looking source package,
+be prepared for a lot more work.
+You will need to read much more, perhaps starting with
+L<dgit-nmu-simple(7)>,
+L<dgit-sponsorship(7)> or
+L<dgit-maint-*(7)>
+
+=head1 SEE ALSO
+
+dgit(1), dgit(7)
diff --git a/dgit.1 b/dgit.1
index 4ec02a7..a26f6bc 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -1,3 +1,4 @@
+'\" t
 .TH dgit 1 "" "Debian Project" "dgit"
 .SH NAME
 dgit \- git integration with the Debian archive
@@ -28,21 +29,24 @@ dgit \- git integration with the Debian archive
 .SH DESCRIPTION
 .B dgit
 allows you to treat the Debian archive as if it were a git
-repository.  See \fBdgit\fP(7) for detailed information about the data
-model, common problems likely to arise with certain kinds of package,
+repository.
+
+This is the command line reference.
+Please read the tutorial(s):
+.TS
+lb l.
+dgit-user(7)   for users: editing, building and sharing packages
+dgit-nmu-simple(7)     for DDs: doing a straightforward NMU
+dgit-maint-native(7)   for maintainers of Debian-native packages
+dgit-maint-merge(7)    for maintainers: using a merging git workflow
+dgit-maint-gbp(7)      for maintainers: using git-buildpackage
+dgit-sponsorship(7)    for sponsors and sponsored contributors
+.TE
+.LP
+See \fBdgit(7)\fP for detailed information about the data
+model,
+common problems likely to arise with certain kinds of package,
 etc.
-
-The usual workflow is:
-.br
-1.     \fBdgit clone\fR or \fBfetch\fR;
-.br
-2.     make, do dev tests, and commit changes in git as desired;
-.br
-3.     build packages for upload, using e.g. \fBdgit sbuild\fR
-.br
-4.     do pre-upload tests of the proposed upload;
-.br
-5.     \fBdgit push\fR.
 .SH OPERATIONS
 .TP
 \fBdgit clone\fR \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir\fR]
@@ -862,71 +866,6 @@ Force on or off the use of the absurd git-apply emulation
 when running gbp pq import
 when importing a package from a .dsc.
 See Debian bug #841867.
-.SH WORKFLOW - SIMPLE
-It is always possible with dgit to clone or fetch a package, make
-changes in git (using git-commit) on the suite branch
-.RB ( "git checkout dgit/" \fIsuite\fR)
-and then dgit push.  You can use whatever gitish techniques you like
-to construct the commits to push;
-the only requirement is that what you push is a
-descendant of the state of the archive, as provided by dgit in the
-remote tracking branch
-.BR remotes/dgit/dgit/ \fIsuite\fR.
-
-If you are using dgit to do an NMU (in Debian),
-and don't know about the
-maintainers' preferred packaging workflows, you should make your
-changes as a linear series of (logicially separated) commits on top of
-what's already in the archive.
-
-If you are lucky the other uploaders have also used dgit and
-integrated the other relevant git history; if not you can fetch it
-into your tree and cherry-pick etc. as you wish.
-.SH WORKFLOW - INTEGRATING BETWEEN DGIT AND OTHER GIT HISTORY
-If you are the maintainer of a package dealing with uploads made
-without dgit, you will probably want to merge the synthetic commits
-(made by dgit to represent the uploads) into your git history.
-Normally you can just merge the dgit branch into your own master, or
-indeed if you do your work on the dgit local suite branch
-.BI dgit/ suite
-you can just use dgit pull.
-
-However the first time dgit is used it will generate a new origin
-commit from the archive which won't be linked into the rest of your
-git history.  You will need to merge this.
-
-If last upload was in fact made with git, you should usually proceed
-as follows: identify the commit which was actually used to build the
-package.  (Hopefully you have a tag for this.)  Check out the dgit
-branch
-.RB ( "git checkout dgit/" \fIsuite\fR)
-and merge that other commit
-.RB ( "git merge debian/" \fIversion\fR).
-Hopefully this merge will be trivial because the two trees should
-be very similar.  The resulting branch head can be merged into your
-working branches
-.RB ( "git checkout master && git merge dgit/" \fIsuite\fR).
-
-If last upload was not made with git, a different approach is required
-to start using dgit.  First, do
-.B dgit fetch
-(or clone) to obtain a git history representation of what's in the
-archive and record it in the
-.BI remotes/dgit/dgit/ suite
-tracking branch.  Then somehow, using your other git history
-plus appropriate diffs and cherry picks from the dgit remote tracking
-branch, construct a git commit whose tree corresponds to the tree to use for the
-next upload. 
-
-between what's in the archive and what you intend to upload.
-Then run
-.BR "dgit push"
-to actually upload the result.
-
-If the commit-to-be-uploaded is not a descendant of the
-dgit remote tracking branch, you will need to pass
-.B --overwrite
-to dgit.
 .SH CONFIGURATION
 dgit can be configured via the git config system.
 You may set keys with git-config (either in system-global or per-tree
@@ -1075,42 +1014,31 @@ and other subprograms and modules used by dgit are affected by various
 environment variables.  Consult the documentaton for those programs
 for details.
 .SH BUGS
-dgit's git representation of format `3.0 (quilt)' source packages does
-not represent the patch stack as git commits.  Currently the patch
-series representation cannot round trip between git and the archive.
-Ideally dgit would represent a quilty package with an origin commit of
-some kind followed by the patch stack as a series of commits followed
-by a pseudo-merge (to make the branch fast-forwarding).  This would
-also mean a new `dgit rebase-prep' command or some such to turn such a
-fast-forwarding branch back into a rebasing patch stack, and a `force'
-option to dgit push (perhaps enabled automatically by a note left by
-rebase-prep) which will make the required pseudo-merge.
-
-If the dgit push fails halfway through, it should be restartable and
-idempotent.  However this is not true for the git tag operation.
-Also, it would be good to check that the proposed signing key is
+There should be
+a `dgit rebase-prep' command or some such to turn a
+fast-forwarding branch containing pseudo-merges
+back into a rebasing patch stack.
+It might have to leave a note
+for a future dgit push.
+
+If the dgit push fails halfway through,
+it is not necessarily restartable and
+idempotent.
+It would be good to check that the proposed signing key is
 available before starting work.
 
-dgit's handling of .orig.tar.gz is not very sophisticated.  Ideally
-the .orig.tar.gz could be transported via the git repo as git tags.
-Doing this is made more complicated by the possibility of a `3.0
-(quilt)' package with multiple .orig tarballs.
-
-dgit's build functions, and dgit push, should not make any changes to
+dgit's build functions, and dgit push, may make changes to
 your current HEAD.  Sadly this is necessary for packages in the `3.0
 (quilt)' source format.  This is ultimately due to what I consider
 design problems in quilt and dpkg-source.
 
-There should be an option which arranges for the `3.0 (quilt)'
-autocommit(s) to not appear on your HEAD, but instead only in the
-remote tracking suite branch.
-
 --dry-run does not always work properly, as not doing some of the git
 fetches may result in subsequent actions being different.  Doing a
 non-dry-run dgit fetch first will help.
+--damp-run is likely to work much better.
 .SH SEE ALSO
 \fBdgit\fP(7),
-\fBdgit-maint-merge\fP(7),
+\fBdgit-*\fP(7),
 \fBcurl\fP(1),
 \fBdput\fP(1),
 \fBdebsign\fP(1),
diff --git a/dgit.7 b/dgit.7
index cbf91b9..6f5844b 100644 (file)
--- a/dgit.7
+++ b/dgit.7
@@ -11,6 +11,22 @@ using dgit.  This git history is stored in a canonical location known
 as
 .B dgit-repos
 which lives on a dedicated git server.
+
+git branches suitable for use with dgit
+can be edited directly in git,
+and used directly for building binary packages.
+They can be shared using all conventional means for sharing git
+branches.
+It is not necessary to use dgit to work with dgitish git branches.
+However, dgit is (usually) needed in order to convert to or from
+Debian-format source packages.
+.SH SEE ALSO
+.TP
+\fBdgit\fP(1)
+Reference manual and documentation catalogue.
+.TP
+\fBdgit-*\fB(7)
+Tutorials and workflow guides.  See dgit(1) for a list.
 .SH MODEL
 You may use any suitable git workflow with dgit, provided you
 satisfy dgit's requirements:
@@ -37,9 +53,6 @@ dgit push will also make signed tags called
 and push them to dgit-repos.  These are used at the
 server to authenticate pushes.
 
-dgit push can operate on any commit which is a descendant of the
-current dgit/suite tip in dgit-repos.
-
 Uploads made by dgit contain an additional field
 .B Dgit
 in the source package .dsc.  (This is added by dgit push.)
@@ -48,29 +61,87 @@ branch) whose tree is identical to the unpacked source upload.
 
 Uploads not made by dgit are represented in git by commits which are
 synthesised by dgit.  The tree of each such commit corresponds to the
-unpacked source; there is an origin commit with the contents, and a
+unpacked source; there is a
+commit with the contents,
+and a
 pseudo-merge from last known upload - that is, from the contents of
 the dgit/suite branch.
+Depending on the source package format,
+the contents commit may have a more complex structure,
+but ultimately it will be a convergence of stubby branches
+from origin commits representing the components of the source package.
 
-dgit expects repos that it works with to have a
+dgit expects trees that it works with to have a
 .B dgit
-remote.  This refers to the well-known dgit-repos location (on a
-dedicated Debian VM).  dgit fetch updates the remote tracking branch
-for dgit/suite.
+(pseudo) remote.  This refers to the dgit-created git view of
+the corresponding archive.
+
+The dgit archive tracking view is synthesised locally,
+on demand,
+by each copy of dgit.
+The tracking view is always a descendant of the
+dgit-repos suite branch (if one exists),
+but may be ahead of it if uploads have been done without dgit.
+The archive tracking view is always fast forwarding within
+each suite.
 
-dgit does not (currently) represent the orig tarball(s) in git.  The
+dgit push can operate on any commit which is a descendant of
+the suite tracking branch.
+
+dgit does not make a systematic record of
+its imports of orig tarball(s).
+So it does not work by finding git tags or branches
+referring to orig tarball(s).
+The
 orig tarballs are downloaded (by dgit clone) into the parent
 directory, as with a traditional (non-gitish) dpkg-source workflow.
 You need to retain these tarballs in the parent directory for dgit
 build and dgit push.
+(They are not needed for purely-git-based workflows.)
 
-dgit repositories could be cloned with standard (git) methods. The
-only exception is that for sourceful builds / uploads the orig
-tarball(s) need to be present in the parent directory.
+dgit repositories could be cloned with standard (git) methods.
+However,
+the dgit repositories do not contain uploads not made with dgit.
+And
+for sourceful builds / uploads the orig
+tarball(s) will need to be present in the parent directory.
 
-To a user looking at the archive, changes pushed using dgit look like
+To a user looking at the archive, changes pushed
+in a simple NMU
+using dgit look like
+reasonable
 changes made in an NMU: in a `3.0 (quilt)' package the delta from the
-previous upload is recorded in a new patch constructed by dpkg-source.
+previous upload is recorded in new patch(es) constructed by dpkg-source.
+.SH LIMITATIONS
+Because the synthesis
+of the suite tracking branches
+is done locally based only on the current archive state,
+it will not necessarily see every upload
+not done with dgit.
+Also, different versions of dgit
+(or the software it calls)
+might import the same .dscs differently
+(although we try to minimise this).
+As a consequence, the dgit tracking views of the same
+suite, made by different instances of dgit, may vary.
+They will have the same contents, but may have different history.
+
+There is no uniform linkage between the tracking branches for
+different suites.
+The Debian infrastructure
+does not do any automatic import of uploads made without dgit.
+It would be possible for a distro's infrastructure to do this;
+in that case,
+different dgit client instances
+would see exactly the same history.
+
+There has been no bulk import of historical uploads into
+Debian's dgit infrastructure.
+To do this it would be necessary to decide whether to
+import existing vcs history
+(which might not be faithful to dgit's invariants)
+or previous non-Dgit uploads
+(which would not provide a very rich history).
 .SH READ-ONLY DISTROS
 Distros which do not maintain a set of dgit history git repositories
 can still be used in a read-only mode with dgit.  Currently Ubuntu
@@ -105,6 +176,39 @@ If you are a quilt user you need to know that dgit's git trees are
 directory (which is used by quilt to record which patches are
 applied).  If you want to manipulate the patch stack you probably want
 to be looking at tools like git-dpm.
+.SH SPLIT VIEW QUILT MODE
+When working with git branches intended
+for use with the `3.0 (quilt)' source format
+dgit can automatically convert a suitable
+maintainer-provided git branch
+(in one of a variety of formats)
+into a dgit branch.
+
+When a split view mode is engaged
+dgit build commands and
+dgit push
+will, on each invocation,
+convert the user's HEAD into the dgit view,
+so that it can be built and/or uploaded.
+
+dgit push in split view mode will push the dgit view to the dgit
+git server.
+The dgit view is always a descendant of the maintainer view.
+dgit push will also make a maintainer view tag
+according to DEP-14
+and push that to the dgit git server.
+
+Split view mode must be enabled explicitly
+(by the use of the applicable command line options,
+subcommands, or configuration).
+This is because it is not possible to reliably tell
+(for example)
+whether a git tree for a dpkg-source `3.0 (quilt)' package
+is a patches-applied or patches-unapplied tree.
+
+Split view conversions are cached in the ref
+dgit-intern/quilt-cache.
+This should not be manipulated directly.
 .SH FILES IN THE SOURCE PACKAGE BUT NOT IN GIT - AUTOTOOLS ETC.
 This section is mainly of interest to maintainers who want to use dgit
 with their existing git history for the Debian package.
@@ -228,5 +332,3 @@ This is 100% reliable, but has the downside
 that if you forget to git add or to commit, and then use
 .BR "dgit -wg" " or " "git reset --hard" ,
 your changes may be lost.
-.SH SEE ALSO
-\fBdgit\fP(1).
diff --git a/local-pod-man b/local-pod-man
new file mode 100755 (executable)
index 0000000..3c3e0ea
--- /dev/null
@@ -0,0 +1,13 @@
+#!/bin/bash
+set -e
+
+case "$#.$1" in
+1.[^-]*) ;;
+*) echo >&2 'usage: ./local-pod-man dgit-something[.7[.pod]]'; exit 16;;
+esac
+base="$1"
+base="${base%.pod}"
+base="${base%.7}"
+
+make "$base.7"
+man -l "$base.7"