release

(Release a software package)

SYNOPSIS

release [-hsv] [-b | -d] package

release -u

REQUIREMENTS

Python 2.5 or later, GnuPG for signing releases, and the revision control program for whatever revision control software is used for the source. Building Debian packages additionally requires pbuilder be installed and properly configured. Git is used to commit changes to the .verisons file.

This program is very likely to require customization if used by anyone other than its author.

DESCRIPTION

release automates portions of the process of releasing a new version of a software package or script. It's actions and all relevant paths are controlled by a configuration file (see CONFIG FILE below). It understands a variety of revision control systems and build systems and attempts to determine the correct thing to do automatically with a minimum of configuration. It updates a .versions file for use by spin for generating web pages.

The default action, if no arguments but package are given, is to create a detached GnuPG signature of the package if it is a tarball release (not a script), copy it to its copy location, create or update symlinks without the embedded version to point to the latest version, archive old versions if appropriate, and update .versions. In this mode, it expects the tarball or script to have already been prepared for a release, although for a script it may export the final version from CVS.

If the -d option is given, release instead generates a tarball release by running the appropriate build actions. It currently understands how to do exports from CVS, Subversion, bzr, and Git and how to generate tarball releases for packages using Automake, Perl's build system, or a dist Makefile target, with or without a configure script.

If the -b option is given, release instead builds Debian packages. It knows how to combine a tarball release with a debian directory stored in CVS or Subversion to build a package. All package builds are done with pdebuild. This mode is no longer tested.

If the -u option is given, release does not expect a package on the command line. Instead, it scans the .versions file and checks the release version against the current version information, as best as it is able to determine, for each package listed there. For any that appear to have a newer release than is recorded in the .versions file, it prints out the package and its current version. Currently, it only checks scripts.

OPTIONS

-b, --build

Build a Debian package as described above. This option is no longer tested and is not used by the author, who has switched to git-buildpackage and separate repository branches for Debian package builds.

-d, --dist

Rather than release software, generate the release tarball. release first exports the package from its revision control system and then runs the appropriate build system commands to generate a release tarball. It understands CVS, Subversion, bzr, and Git for revision control systems and Perl, Automake, Autoconf, and simple makefiles with a dist target for generating the release tarball.

-h, --help

Prints basic usage information for release.

-s, --source

When building a Debian package with -b, force inclusion of the full source in the *.changes file by passing -sa to pbuilder in the --debuildopts argument.

-u, --unreleased

Rather than release software, scan the .versions file and check all scripts listed there to see if they have a different version than the one recorded in .versions.

-v, --version

Print out the version of release and exit.

CONFIG FILE

release uses a configuration file for most of the information it needs. This configuration file is in the format parsed by the standard Python ConfigFile class (similar to a Windows INI file) and should have one section per package, as used for command-line arguments. It also must have a section entitled PATHS that configures some global variables. Blank lines and lines beginning with # are ignored.

Sections start with the section title between []. A variable setting is the variable name, a colon, whitespace, and then the value. For example:

    [PATHS]
    distdir: /home/eagle/data/dist
    versions: /home/eagle/web/eagle/.versions

    [kstart]
    tarball: /home/eagle/data/dist
    prefix: kstart
    copy: /afs/ir/users/r/r/rra/public/software/kerberos
    archive: /afs/ir/users/r/r/rra/public/software/ARCHIVE/kstart
    package: kstart
    giturl: /home/eagle/dvl/kstart

Variables for the PATHS section:

builddir

Specifies where to put Debian packages built using the -b option. Required only if -b is used.

distdir

Specifies where to put tarballs built using the -d option. This location will then generally be named in the tarball parameter of the relevant package configuration section. Required only if -d is used.

versions

Specifies the location of the .versions file for spin that release should update. Required.

Variables for each package section:

archive

When copying a new tarball release, look for any older files from previous versions and move them to this directory, which is created if it doesn't already exist. Older files are recognized by looking for files starting with prefix and matching the file name pattern for a tarball with a version or its MD5 checksum or PGP signature. Only used if tarball is set; there is no way to archive old versions of scripts.

bzrurl

The URL to the bzr repository for the package. When -d is given, it is used with the bzr branch command to generate an exported copy of the repository, which is then used to run the appropriate command to generate a distribution tarball.

copy

The location into which to copy the release, either a script or a tarball. For tarballs, files from previous versions in that location will be left there unless archive is also set. For scripts, any existing version will be overwritten.

cvsdebpath

The path to the CVS module for the Debian build rules within a CVS repository. This is only used when building a Debian package for a script using the -b option and is no longer tested.

cvspath

The path to the CVS module for the package within a CVS repository. When -d is given, it is used with the cvs export command to generate an exported copy of the repository, which is then used to run the appropriate command to generate a distribution tarball. It is also used to locate the script in the CVS repository to generate a CVS export when the export variable is set instead of copy. If cvsroot is not also set, the default CVS root is used, which may be unpredictable.

cvsroot

Specifies the root of the CVS repository for use with cvspath. Setting this variable is strongly recommended, even if you have CVS configured to use a default repository and all packages are in that repository, since it removes potential future ambiguity.

export

Normally, scripts are copied from the location specified by script to the location specified by copy. If this variable is set instead of copy, the script is instead exported from its CVS repository, expanding CVS keywords (the -kv option). cvspath must be set. This is only used when script is set and should not be set for the same package as copy.

gitbranch

The branch to export when generating a distribution tarball, instead of master. Only used with -d and if giturl is set.

giturl

The URL, which may be a file system path, to the Git repository for the package. When -d is given, it is used with the git archive command to generate an exported copy of the repository, which is then used to run the appropriate command to generate a distribution tarball. By default, the master branch is exported, but a different branch may be specified with gitbranch. Only used if tarball is set.

keyid

If set, names PGP key IDs to use when signing tarball releases. Setting this causes the -u option and this value to be passed to gpg when creating signatures. The value will be split on whitespace and each word will be taken to be a separate key. If more than one key is listed, the resulting detached signature file will contain multiple signatures. Only used if tarball is set.

maketarget

The make target to use to generate a distribution tarball. This overrides the default of distcheck for Automake package and dist for any other package with a Makefile or configure script. This is only used if tarball is set and when the -d option is given.

package

The name of the Debian source package. Only used when building Debian packages with -b. This need not match the package name in the tarball, which should be given with prefix. It should patch the package name in debian/changelog.

prefix

The prefix for tarballs of this package. Release tarballs are expected to be named prefix-version.tar.gz. Only used if tarball is also set.

script

Specifies the location of a script to release. release will determine the version of the script by searching the file for either a CVS Id string or a variable VERSION or $VERSION within the first 50 lines of the file. The latter overrides the former. The presence of this variable indicates that the package is a script, as opposed to tarball which indicates tarball releases.

svnurl

The URL to the Subversion repository for the package. When -d is given, it is used with the svn export command to generate an exported copy of the repository, which is then used to run the appropriate command to generate a distribution tarball.

tarball

Specifies the location searched for the tarball to release. The resulting directory will be searched for tarballs starting with prefix and the version number of the release extracted from the file name. The presence of this variable indicates that this package has tarball releases (as opposed to script, which indicates a script.

Only one of bzrurl, cvspath, giturl, or svnurl should be given.

FILES

~/dvl/CONFIG/release.conf

The default configuration file location, set at the top of this script.

BUGS

release hard-codes all sorts of details about the package layout, export preferences, and version control methods of its author. It will likely require extensive customization to work for someone else. This is particularly true of the Debian package building (-b), which relies on a particular way of storing Debian package build information alongside a package in a CVS or Subversion repository.

Debian package builds (-b) are no longer used by the author and no longer tested. The same is true for all tarball support for revision control systems other than Git, although it's simple enough that it's unlikely to break significantly.

SEE ALSO

bzr(1), cvs(1), git(1), pdebuild(1), spin(1), svn(1)

The current version of this script is available from Russ Allbery's script page at <http://www.eyrie.org/~eagle/software/scripts/>.

AUTHOR

Russ Allbery <rra@stanford.edu>

COPYRIGHT AND LICENSE

Copyright 2001, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2012 Russ Allbery <rra@stanford.edu>.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Last spun 2014-07-28 from POD modified 2014-07-27