If a package is available in the official backports, use it. If you need to backport something not backported, make a sloppy backport from testing/unstable to stable/oldstable, or must make changes for afs and kerberos support, read on.
1. 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/src/{backports,fork}/<pkg>
cd /afs/hcoop.net/common/debian/src/{backports,fork}/<pkg>
# Browse http://packages.debian.org/<pkg> and find a link to a dsc file
# If you already have the .dsc, .diff.gz, and orig tarball downloaded
# to the current directory, then skip this step.
gbp import-dsc --debian-branch=debian --upstream-branch=upstream http://path/to/file.dsc
cd <pkg>These last two steps create 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. If you are not, create it with git checkout -b master
Make your HCoop-specific changes (preferably in an incremental and atomic fashion) and commit them using git. You may want to use quilt and commit the quilt patches instead if the package uses quilt.
1.1. hcoopifying the debian package
Open debian/changelog in emacs and invoke M-x debian-changelog-mode.
Press C-c C-v to create a new entry in the changelog and append +hcoopN (where N is the hcoop revision) to the version. E.g. 0.60.0-3 become 0.60.0-3+hcoop1
If it is a backport, change the distribution to $stable-backports (as of 2015, this is jessie-backports). The version should also have ~bpo8+hcoopN for jessie, ~bpo70+hcoopN for wheezy (~bpo7+hcoopN for a sloppy backport), or ~bpo60+hcoopN for squeeze appended to conform to standard backports versioning.
- Add a comment
Press C-c C-c to close the entry.
- Save and exit.
Alternatively, you can use git-dch for this task if you ensure that your git commits work as debian changelog entries.
2. 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 <pkgname> gbp import-dsc --debian-branch=debian http://path/to/file.dsc
git-import-dsc should do the right thing.
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.
3. New upstream version not yet in Debian
This section needs decrufting and may produce unexpected results. It also makes it difficult for the package for sync with Debian again in the future.
If you want to update an existing custom HCoop Debian package with a new version of the upstream program, and no Debian package yet exists for that version, then you'll need to work with the upstream tarball for the new release directly. Instructions are as follows.
Make a directory for the new version.
cd /afs/hcoop.net/common/debian/<pkgname> mkdir <ver> cd <ver>
- Download the new upstream tarball to this directory.
Rename it to <pkgname>_<ver>.orig.tar.gz.
Move the git repo for the old version over to the new directory.
mv ../<old-ver>/<pkgname> .
Run git-import-orig.
cd <pkgname> git-import-orig ../<pkgname>_<ver>.orig.tar.gz
- Resolve conflicts and built the new package.
When Debian catches up to our blazing pace and makes their own package, perhaps with changes that we want, then we will need to use some trickery to make the packages sync up.
Change directory to /afs/hcoop.net/common/debian/<pkgname>/<ver>.
Obtain the debian .dsc file and extract the contents to <pkgname>-<ver>, as in New package from Debian section.
Switch to the debian branch.
cd <pkgname> git checkout debian
Check in Debian's changes.
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> git add . ; git reset --hard
Do an "ours" merge with the upstream branch. This basically does a merge that is guaranteed not to have conflicts, with the end result being the contents of the current branch. This allows us to more easily merge in the changes that Debian made, later on.
git merge -s ours upstream
For instructive purposes, do a git log. You will see a log entry for the upstream version just below the log entry for the new Debian package. Very nifty.
Now switch back to the master branch which contains our changes and merge from the debian branch.
git checkout master git merge debian
Resolve any conflicts. You shouldn't see conflicts in the upstream source -- only the debian/ directory might have conflicts.
- Build and tag the package, making a new HCoop version.