Building Debian Dependencies/Dependency Guidelines

These are the guidelines for adding a dependency to Koha, especially when this dependency isn't already in the minimum Debian version we support.

The goal of backporting modules is twofold:

• to make an out-of-the-box installation of Koha from Debian packages possible, even on older releases, and
• to allow newer versions of modules to be used than might be available in the oldest thing we support.

There's a bit of natural conflict between these two things (trying to support new and old at the same time), so most of the guidelines here are about reducing the friction involved.

The Easy Case

1. If the dependency you want to add is in Wheezy and Jessie already, accounting for versions, then that's fine. A shoutout to the package maintainer that dependency changes have happened is useful, but that's about it.

The Other Cases

1. If you can reasonably avoid adding a dependency, do it. It's not always possible, but some things don't need to be there because it saves a few minutes of coding. If it saves you hours, then it's probably reasonable to consider adding it.
2. Check the copyright. The Koha project is not going to redistribute a module just because it's in CPAN. Being in CPAN doesn't cause a default license to be applied, so if the module doesn't have something that says that it can be redistributed, the default position in copyright law is that it is illegal to redistribute it.
3. Figure out the minimum version that'll work. Don't just add the latest version because that's what you grabbed out of CPAN. If it works with a more commonly distributed version then you've saved many people a lot of time by declaring that. A bit more guidance on that here: http://mail.librecat.org/pipermail/librecat-dev/2015-May/000380.html
4. Small, standalone modules will in most cases be easy to deal with. Things with many complex dependencies will not. The latter may cause backporting the module to be impossible, in which case it just won't happen.
5. Point it out to the package maintainer early, not right before it's going to be released. On one hand, they can tell you then if it's going to be impossible. On the other, all the testers and QA people will have access to the dependency if it's already in the repo when it comes time for signing off, making their lives easier. If the package maintainer only hears about a necessary package at the last moment, then your package will be delayed. Especially, don't rely on QA to pass this along while they're looking at it.
6. All packages that are created are submitted into Debian. If they don't get into Debian, then they don't get into Koha. Debian is pretty strict, so in turn the package maintainer has to be pretty strict. The reason for this is, in part, that it means that the amount of modules we have to care about won't (hopefully) just keep getting bigger, there's a chance it'll go down too over time. Also, a long term goal is to get Koha packages into Debian proper.
7. It's quite possible to create packages of modules using dh-make-perl, but almost invariably these will have problems, mostly minor, that prevent them going into Debian. These are found by running the lintian tool over a package. Generally, fixing these is quick and easy. Sometimes there are many problems. It is the responsibility of the people who want this dependency to aid in resolving these issues. Help is available, find the packaging maintainer on IRC or koha-devel if you need to.
   1. There is a guide to help you get started. This contains the basics that you need to know.
   2. If you don't help out with this when necessary, your dependency is likely to go to the bottom of the packaging queue. If you do, it'll ne nearer the top :)
8. To get a feel for something being easy to package, do:
   dh-make-perl --pkg-perl --build --cpan Module::Name
   with the lintian config set up from that wiki page. Best if you can do this in a Wheezy environment. If you get only a few lintian errors (and some you'll see in every case), and you get a .deb file out then end, that's a good sign. Even better if from there you tidy it up, commit it to alioth, and ask the package maintainer on the relevant bug to have a look over it for you :)

Other Worthwhile Thing

• The Debian pkg-perl team is very helpful and worth joining.