Building this package for Debian
--------------------------------

This source package need no special handling for normal package builds.


Developing this package for Debian
----------------------------------

The source of this package is developed using git and the helper tool
git-buildpackage, with all official releases tagged and signed and
binary diffs of tarballs stored using pristine-tar.  This is documented
below /usr/share/doc/git-buildpackage/manual-html/ .

Upstream development is tracked both in the Git branch "upstream-git"
and using upstream tarballs.

A custom build target shows current upstream and packaging versions:

    debian/rules print-version

Current upstream tarball can be prepared using this other build target:

    debian/rules get-orig-source

To switch to newer upstream source, first add a dummy changelog entry
and comment out DEB_UPSTREAM_TARBALL_MD5 before getting the source:

    dch -v ${new_upstream_version}-1 "Dummy changelog entry"
    sed -i -e 's/^\(DEB_UPSTREAM_TARBALL_MD5\b\)/#\1/' debian/rules
    debian/rules get-orig-source

Store new md5sum to help ensure identical source is received later.

Before injecting a newer upstream tarball, use below commands to sync
with upstream Git, to adopt upstream commit messages and to minimize
size of our Git.

The following commands updates the local mirror of upstream source:

    git checkout upstream-git
    git pull
    git fetch --tags

The following command shows upstream changes possibly relevant to merge
or cherry-pick (replace leading "upstream" with "HEAD^" and invoke
immediately after syncing to show recently merged changes possibly
relevant to mention in our changelog):

    git log --pretty="format:%h %s" upstream..upstream-git

The following commands merges all upstream changes with our packaging
branches (to skip newest upstream changes, replace dot in first pull
command with either a tag or an explicit commit hash):

    git checkout upstream
    git pull . upstream-git
    git checkout master
    git pull . upstream

If git-import-orig fails complaining about no changes, revert both pulls
(using "git reset --hard HEAD^" in both master and upstream branches),
and try again skipping the very newest changes to cheat git-import-orig.

To do a package release from upstream Git snapshot, first look at
upstream development for a good place to release, and tag by its date,
replacing "~" with "." to mimic git-buildpackage logic (replace
timestamp and commit hash below with real ones based on chosen commit).

    git log --abbrev-commit upstream-git
    git tag -s -m "Upstream snapshot" upstream/0.2.git20080130 61279f8
    dch -r -v "0.2~git20080130-1" "New upstream Git snapshot."

Setting DEB_MAINTAINER_MODE=1 enables additional build routines helpful
during development of the package, but unfit for normal builds.  This
typically includes the CDBS feature of auto-updating debian/control with
CDBS-related build-dependencies, which is forbidden by Debian Policy as
build environment must not change during automated builds.


Maintaining packaging build routines
------------------------------------

This source package wraps debhelper commands and other tedious parts of
the build routines using the CDBS framework.  Please refer to the actual
makefile snippets included from debian/rules for details on their
purpose and ways to override defaults.  Additionally, makefile snippets
included from below /usr/share/cdbs may also be documented in
/usr/share/doc/cdbs/cdbs-doc.pdf.gz .


 -- Jonas Smedegaard <dr@jones.dk>  Sun, 29 Mar 2009 16:02:47 +0200
