==============================================
A Heuristic-based Process for Backporting Debs
==============================================

For the purposes of this document, i'll assume you're backporting from
testing (sarge) to stable (woody).
Any distribution that contains >= package versions will work too.

You rarely want to do the backport process on the target system.
Doing it in a chroot will work just fine.

The philosophies of this procedure are:
  - packages in the stable distribution are preferred over packages from
    the testing distribution that install cleanly without a rebuild, followed
    by packages that must be backported.  this is true for both the target
    system and the build environment.
  - when the day comes that you want to upgrade your whole system to 
    a version of the distro that includes the version of the package
    you've backported (e.g., a new stable release), the transitition should be
    smooth, and the target distro's version should be preferrered over the
    backported version.

The idea is to systematically determine what needs to be backported, letting
apt do the dependency checking for you.  Keeping a simple local apt source
simplifies this by avoiding using the dpkg command directly.

Also, backports.org is a useful resource for finding already-backported
build dependencies - I recommend checking there before going too far down
a dependency chain.

Setting Up a Build Environment
==============================
You can build a chroot with the debootstrap command.
For example, when I'm backporting to woody, I do something like this:
  mkdir /home/chroots/woody
  debootstrap woody /home/chroots/woody http://http.us.debian.org/debian

Then I copy a simple sources.list into the chroot:
------------------------------------------------------------------------------
# See sources.list(5) for more information, especialy
# Remember that you can only use http, ftp or file URIs
# CDROMs are managed through the apt-cdrom tool.
deb http://http.us.debian.org/debian woody main
deb http://security.debian.org stable/updates main
# backports
deb file:///tmp/ ./
 
# Uncomment if you want the apt-get source function to work
deb-src http://http.us.debian.org/debian testing main
------------------------------------------------------------------------------

Backporting Packages
====================
The following pseudo code describes the procedure I follow.
Its theoretically automatable, for the most part, but there are cases of
circular dependencies that will bite you.  There are also times when
making a small change (disabling some of the binary packages produced
by a source package, for example) can prevent build-dependency chain hell.

## regenerate the packages file & updateAdd a 
update_sources() {
  cd /tmp
  apt-ftparchive packages . > Packages
  apt-get update
}

## you know you need a newer package, but don't know if you need
## to actually rebuild anything yet.
get_new_package($pkg) {
  - add a deb entry to your sources.list for testing
    (don't replace your stable entry, just add a new one)
  - update_sources
  - apt-get --dry-run install $pkg (just to see what it will bring in)
  - remove testing entry from sources.list

  did it show an acceptable set of dependencies from testing?
    - if so - apt-get install $pkg
    - else backport($pkg)
}

## a rebuild is necessary, recurse till you have all the build-deps, then
## build the desired package
backport($pkg) {
  - cd /tmp
  - apt-get source $pkg
  - cd $pkg-$version
  - add a debian/changelog entry, usually just noting that you're doing a
    backport
  - modify version string in debian/changelog
    the algorithm i use is (pkgversion - 1).woody0
    for example,
      3.2.4-3 -> 3.2.4-2.woody0
      0.64 -> 0.63.woody0
      1.5-1 -> 1.5-0.woody0
    this way, when we upgrade to sarge, we'll get the sarge packages.
    the woody number can be incremented if we need to spin a new backport 
    for the same package version
  - modify any versioned deps in debian/control.  keep in mind that this
    file might be build-time generated, and that other packages may
    have versioned dependencies on it.
  - dpkg-buildpackage
  
  does it build?
    - if so, update_sources() and apt-get install it.
    - missing build-deps?
      for each build-dep:
        - get_package($build_dep)
            - is the build-dep opening up a can of worms?
              can we get around it?  (for example, disabling some of the binary
                                    packages it removes, etc)
    - backport($pkg) again
}

## we need a package - one from the current distro is preferred
## if we can't get that, get it from the newer distro
get_package($pkg) {
  - apt-get --dry-run install $pkg
  
  is it available and of the proper version?
    - if so, apt-get install $pkg
    - else get_new_package($pkg)
}

main($pkg)
  get_package($pkg)

Installing the backported package
=================================
  Once you have a backported deb, along with possibly some backported
dependencies, you can use this process to install/upgrade the minimal
set of packages on your target system.

I strongly suggest testing this procedure on another system, or in a chroot
before doing it on your target system.

1. Create a directory, say /var/local/backports, and drop in the .deb for
   the package you are trying to backport.
2. cd /var/local/backports; apt-ftparchive packages . > Packages
3. add a sources.list entry for your /var/local/backports directory
   ex:
     deb file:///var/local/backports/ ./
4. apt-get update; apt-get install $pkg
5. hopefully all the dependencies it needs can be pulled from the current
   distribution - however, it may complain about packages that aren't 
   available.  backport each dependency in your build chroot, and add
   only the missing debs to /var/local/backports.
6. goto step 4 - cycle till done.