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$ debsign ~/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$ fakeroot debian/rules clean
me@home:~/deb/mypack$ hg commit
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
me@home:~/deb/mypack$ quilt push
me@home:~/deb/mypack$ quilt refresh
me@home:~/deb/mypack$ quilt push
me@home:~/deb/mypack$ quilt refresh

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-port 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
----

buildpackage should also copy build errors to .build log.

buildpackage and port should complain about reserved branches.

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

buildpackage should use heuristics to complain about changelog versions
that look wrong wrt. present tags, eg., when a new source has been
imported but a new changelog is missing.

Find a way to automate the process of taking a patch generated by
dpkg-source 3.0 (quilt) and turn it into a properly named patch and
clean up .pc directory.  (Unless Quilt has something that does this.)

Support and describe single-debian-patch mode:
  Convert to 3.0 (quilt) format and keep it out of mercurial:
  echo "3.0 (quilt)" >debian/source/format
  echo "debian/patches" >>.hgignore
  echo ".pc" >>.hgignore
  And then pass --single-debian-patch to mercurial-buildpackage.

Outline what each binary does, eg. importorig ~=  ..., quilt pop -a, hg
merge -f -r upstream, hg commit, dch -v fullVersion, ...

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.

Support xz compression.

Figure out how to incorporate Mercurial Queues as patch system.

Figure out how to support heuristics suggested by Goswin von Brederlow
in #560189.
