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.


COMMITTING CODE CHANGES
-----------------------

If you're in the collab-maint group on Alioth, you're welcome to hack on the
source and directly commit changes.

Use of branches for non-trivial changes is encouraged. That way, they can be
tested independently and merged as needed for release.


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.

Let mercurial-buildpackage have an option to just create the source
package.

Figure out how to support heuristics suggested by Goswin von Brederlow
in #560189.  With several tarballs, we cannot just use the directory
structure, because then we cannot tell the main tarball from the
components.  So maybe a single --main buzz53.tgz would suffice for
separation, and then use the name of the single directory at the root in
each component?

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

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 in terms of shell commands, eg. importorig
~= ..., quilt pop -a, hg merge -f -r upstream, hg commit, dch -v
fullVersion, ...

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

Figure out how to incorporate Mercurial Queues as patch system.

Make it possible to fix a broken pristine set, eg:
hg up pristine
cp  ../package.orig.tar.gz .
rm package.orig.tar
gunzip package.orig.tar.gz 
xdelta delta -p recreated-package.orig.tar package.orig.tar package.orig.tar.xdelta 
pristine-gz gendelta ../package.orig.tar.gz package.orig.tar.gz.pristine 
hg commit -m 'Repair broken pristine files'

Eliminate the pristine branch and instead put metadata into a special
directory, which must then be ignored when generating the tarballs.

Graciously handle existing changelog entries: Check that the
to-be-auto-generated version matches a possibly existing one, and if it
does, skip creating it.
