backport

(Backport a Debian package automatically)

SYNOPSIS

backport [-abhpv] [-c chroot] [-d dist] [-e entry] [-l version] [-s suffix] [-t target] dsc

DESCRIPTION

backport automates some of the tedium of backporting a Debian package to stable. Given the path to a *.dsc file, it unpacks the source package, adds a changelog entry for the backport with an appropriate version number, fixes build-dependencies that can be handled automatically, and builds the package using pdebuild and cowbuilder.

By default, backport prepares backports for backports.debian.org, using its version number convention. In this case, the -l option, giving the version number of the previous backport or the current stable version, is mandatory. Other backport targets may be specified with the -t option. The dist (target distribution in the changelog) and suffix (version number suffix to append) are set automatically based on the target but can be overridden as needed.

backport adds a debian/changelog entry with the text Backport to dist. plus any specific changelog entries for other significant changes it makes. The invoking user will be added to Uploaders in debian/control unless they are already listed in Maintainer or Uploaders. The urgency of the changelog entry will be the maximum of the urgencies of the changelog entries for the backported package between the version specified with -l and the current version, or the urgency of the most recent change if -l was not given.

The *.dsc file given on the command line must be named according to the normal Debian source package naming convention (package_version.dsc), since it is parsed for package and version information. If it is not named appropriately, the script will fail.

OPTIONS

-a, --add-upstream

Include the upstream *.orig.tar.gz file in the *.changes file and hence in the upload. This is necessary the first time a backport of a particular package is uploaded to an archive. If this option is not given, the upstream tarball is included if and only if the original Debian revision (before backporting) is 1.

-b, --binary

Do a binary-only build, meaning that neither source nor architecture-independent binary package files will be included in the build. This is equivalent to the -B option to dpkg-buildpackage and implemented by passing that option through.

-c chroot, --chroot=chroot

Use the specified chroot instead of the default chroot of base-jessie (or base-wheezy if the distribution is oldstable or contains wheezy, base-squeeze if the distribution contains squeeze, base-lenny if the distribution contains lenny, or base-etch if the distribution contains etch). All chroots must be in /var/cache/pbuilder and end with .cow. This option controls the filename before .cow. In other words, the default chroot is /var/cache/pbuilder/base-jessie.cow, and passing -c ebo would use /var/cache/pbuilder/ebo.cow instead.

-d dist, --dist=dist

The target distribution for the debian/changelog entry. By default, this is jessie-backports for a target of bpo (the default), and stable for any other target. The target distribution is used to choose the version number suffix for the backported package.

-e entry, --entry=entry

Add an additional changelog entry entry after the note that this is a backport but before any information about changes made by this script. This is suitable, for instance, for noting that the backport is a security fix.

-h, --help

Print out this documentation (which is done simply by feeding the script to perldoc -t).

-l version, --last=version

Specifies the previous stable or backported version. If this option is given, the changelog in the *.changes file will include all changelog entries back to that version (by using the -v dpkg-buildpackage option). If it is not given, only the most recent changelog entry (the one for the backport) will be included. This option is required for a target of bpo (backports.debian.org, the default).

-p, --prepare

Do not do the build. Instead, prepare the backport, making required modifications to debian/control and debian/changelog, and then leave the prepared backport in a subdirectory, printing out the command to run to build the package. This is useful for testing or if additional modifications will be needed after the automated work done by backport.

-s suffix, --suffix=suffix

The suffix appended to the version number of the package (after a ~). The default varies based on the selected target and target distribution. For bpo and jessie-backports (the default), it will be bpo8+1. If the distribution isn't one that backport recognizes, you may need to specify the version suffix manually.

-t target, --target=target

The backporting target, used to set other variables, primarily the version suffix appended to the package version. Currently supported targets are bpo, eyrie, and stanford. bpo is the default.

-v, --version

Print out the version of backport and exit.

NOTES

This script avoids some tedium, but it should not be used blindly. The results are not guaranteed to work, and some packages have subtle compatibility issues or other backporting issues that it cannot handle automatically. The results of a backport should always be tested before being uploaded to backports.debian.org or used in a production environment.

BUGS

Currently, most of the interesting settings (such as the target distribution for the backport, or the path to the cowbuilder base chroot) are hard-coded in this script, and it only does backports to jessie, wheezy, squeeze, lenny, or etch. This could be improved in later versions to allow more configuration.

pdebuild and cowbuilder are used unconditionally.

SEE ALSO

cowbuilder(8), dpkg-buildpackage(1), pdebuild(1)

The backports.debian.org contributor documentation, available at <http://backports.debian.org/Instructions/>.

AUTHOR

Russ Allbery <eagle@eyrie.org>

COPYRIGHT AND LICENSE

Copyright 2015 Russ Allbery <eagle@eyrie.org>

Copyright 2007, 2008, 2009, 2010, 2011, 2013 The Board of Trustees of the Leland Stanford Junior University

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

Last modified and spun 2015-08-17