INTRODUCTION
------------

The way to start using mercurial-buildpackage on mypack is as follows.

me@home:~/deb$ hg init mypack
me@home:~/deb$ cd mypack
me@home:~/deb/mypack$ mercurial-importdsc ../mypack_$VERSION1.dsc
me@home:~/deb/mypack$ ...
me@home:~/deb/mypack$ mercurial-importdsc ../mypack_$VERSIONn.dsc
me@home:~/deb/mypack$ mercurial-pristinetar -v

Hack away and prepare a new version of mypack.

me@home:~/deb/mypack$ mercurial-buildpackage -v
me@home:~/deb/mypack$ sudo dpkg -i ../mypack_$NEWVERSION_$ARCH.deb

Check that everything built fine.  Then build in a clean chroot:

me@home:~/deb/mypack$ mercurial-buildpackage -c ~/etc/sid-builderrc
me@home:~/deb/mypack$ sudo dpkg -i ~/presults/mypack_$NEWVERSION_$ARCH.deb

Check that everything works fine when built in chroot.

me@home:~/deb/mypack$ lintian ~/presults/mypack_$NEWVERSION_$ARCH.changes
me@home:~/deb/mypack$ dput ~/presults/mypack_$NEWVERSION_$ARCH.changes

Record that new a version has been uploaded:

me@home:~/deb/mypack$ mercurial-tagversion

Make a backport to Lenny:

me@home:~/deb/mypack$ mercurial-port lenny
me@home:~/deb/mypack$ vi debian/changelog
me@home:~/deb/mypack$ ...
me@home:~/deb/mypack$ mercurial-buildpackage -c ~/etc/lenny-builderrc

Incorporate new upstream releases:

me@home:~/deb/mypack$ mercurial-importorig ../mypack_$VERSION9.orig.tar.gz

And so forth...


DESIGN
------

Mercurial-buildpackage is a reimplementation of the ideas in John
Goerzen's hg-buildpackage.  The goal for mercurial-buildpackage is to
satisfy the following:

 1. Only one repository.  Upstream should be a branch of the repo
    instead of having a separate package.upstream repo.

 2. Changes for backports should also be in the same repo.  Solution:
    branch etch, branch lenny, etc.  A mercurial-backport command is
    then needed to merge the default branch into the lenny (say) branch
    so the backport can start.

 3. Make it possible for mercurial-buildpackage to use
    pbuilder.
 
 4. Consistent, easily parsable output; same format as Lintian or
    Piuparts.

 5. mercurial-tagversion must complain if the repository has uncommited
    changes (unless --force).

 6. Support dpkg source format 3.0.

 7. Allow custom distribution (not just DEBIAN) in tags.  Solution:
    Because each named branch tells which release (and thus implicitly
    which distribution) that branch pertains to, tags along each branch
    can just be <package>_<version>, like "neko_1.2.3-3",
    "haxe_1;2.0-4~bpo50+1", or "vi_2.1.5-2ubuntu1".

 8. It must be possible to use mercurial-importdsc to incorporate the
    full history when converting an existing package.


TODO
----

Check that every operation is properly rolled back if something goes
wrong.

buildpackage and port should complain about reserved branches.

buildpackage should use heuristics to complain about changelog versions
that look wrong in current branch, like ~bpo50 in default branch.
And suggest --include-source.

port should allude to missing use of tagversion when a tag is missing.

Make sure .hgignore containing .pc/ is created on import.
Alternatively, describe what to do when converting to 3.0 (quilt).

Support xz compression.

Figure out how to incorporate Mercurial Queues as patch system.
