This page describes how to make custom Debian packages for HCoop.

[[TableOfContents()]]

= Making a new custom package =

If you want to make changes to an existing Debian package, and we haven't
made our own custom package before, then do the following.

{{{
mkdir -p /afs/hcoop.net/common/debian/<pkg>/<upstream-version>
cd /afs/hcoop.net/common/debian/<pkg>/<upstream-version>
# Browse http://packages.debian.org/<pkg> and find a link to a dsc file
dget -x http://path/to/file.dsc
# Or if you already have the .dsc, .diff.gz, and orig tarball downloaded,
# then do dpkg-source -x path/to/file.dsc instead.
git-import-dsc --debian-branch=debian <pkg>-<ver>.dsc
}}}

This last step creates a subdirectory named after the package.  The subdirectory
has the complete source, including the {{{./debian}}} directory.  The original
tarball (without {{{./debian}}}) is in the "upstream" branch, and the
original stuff plus Debian changes would be in the "debian" branch, and a copy of
the contents of the "debian" branch is placed in the "master" branch.  You will
be in the "master" branch now.

Make your HCoop-specific changes (preferably in an incremental and atomic
fashion) and commit them using git.

= Building a package =

First, make sure you are on the "master" branch by running:

{{{
git branch -l
}}}

If you see an asterisk by "master", you're on the right branch.

If we want to build the package with some uncommitted changes, as a
sanity check, then do:

{{{
git-buildpackage --git-ignore-new
}}}

When it comes time to test the changes, build the package using:

{{{
git-buildpackage
}}}

The packages will be built and placed in the parent directory.  To
indicate that we are done making changes to this particular version of
the Debian package, tag it with:

{{{
git-buildpackage --git-tag
}}}

This makes the package version show up when you do {{{git tag -l}}}, for
easy diffing and viewing.

= New package from Debian =

When a new Debian package comes out, and we want to incorporate their
changes, the routine will be as follows.

 * <pkgname> is the name of the package.
 * <ver> is the upstream version of the software.
 * <patch> is the patch level of the package.  For example: "1".  We always add an "hcoop" suffix to patch levels of packages that we modify.

{{{
cd ..
dget -x <URL to dsc file on packages.debian.org>
cd <pkgname>
git checkout debian
cd ../<pkgname>-<ver>
GIT_DIR=../<pkgname>/.git git add .
GIT_DIR=../<pkgname>/.git git add -u .
GIT_DIR=../<pkgname>/.git git commit -m "Import Debian package <ver>-<patch>"
cd <pkgname>
rm -fr ../<pkgname>-<ver>
git add . ; git reset --hard
git tag -a -m "Debian release <ver>-<patch>" debian/<ver>-<patch>
}}}

OK, let's stop to take a breather.  Here's what the effect of all of this stuff has been.

 * Retrieved a .dsc file from debian and expanded it into the <pkgname>-<ver> directory.
 * Switched to the debian branch.
 * Moved into the new directory.
 * Set GIT_DIR, which specifies the git metadata directory to use.
 * Added all untracked files.
 * Updated all tracked files.
 * Committed the result.  Now the git metadata directory knows about this Debian package version.
 * Removed the <pkgname>-<ver> directory.
 * Reset the working directory to match the metadata, so that we get the latest changes that we just committed.
 * Tagged this particular state with the version of the package.

Now we'll want to switch back to the master branch (where we keep HCoop-specific changes) and merge the latest Debian changes.

{{{
git checkout master
git merge debian
[fix any conflicts, particularly in debian/changelog]
git commit
}}}

Now, make a new debian/changelog entry and list the changes that were kept in our version.  When done, commit, build packages, and tag the version of the package as in the '''Building a Package''' section.

= New upstream package not yet in Debian etch =

Write me.