Preface

This document is part of the LiveSupport project, Copyright © 2004 Media Development Loan Fund, under the GNU GPL.

Scope

This document describes the process of releasing a new version of LiveSupport. Obviously this document is only relevant to people who have the rights and permissions to make such a release.

Introduction

For all the releases of LiveSupport to remain consistent, it is preferable to have a repeatable release process, which will be followed when creating releases. This ensures that no matter who creates the releases, they will remain similar.

The release process boils down to the following steps:

Getting LiveSupport sources

It is assumed that the person doing the release has a read/write access to the LiveSupport version control system. As a first step of the release process, a fresh copy of the version control repository is checked out, so as to insure that:
To get a fresh copy of the LiveSupport repository, execute the following in an empty directory:

cvs -z3 -d :ext:<username>@netfinity-5.mdlf.org:/home/cvs checkout -P livesupport

Where <username> is the user name for accessing the repository of the person making the release.

Checking the distribution script

It is advisable to check the installation script bin/dist.sh, to make sure it refers to up-to-date information from the development environment.

The most important aspect to check is that the specific versions of tools mentioned in the distribution script are in sync with the tools compiled by the master Makefile under the target tools_setup. To check this, compare tool version variables in the two files, e.g. BOOST_VERSION from Makefile with boost_version from bin/dist.sh. Make sure to check the versions for all the tools mentioned in these files. Also check that there are no tools missing from the distribution script that are mentioned in the master Makefile.

Updating release version and changelog

Updating the release version and maintining a changelog helps people track the progress of the project. Also, building binary packages rely on this information, in particular debian packages won't build if there is a mismatch between the release version and the topmost entry in the debian changelog file.

Curently, only the debian changelog keeps track of the changes and the version of LiveSupport. To update the changelog, edit etc/debian/changelog, by inserting a section onto the top of the file:

livesupport (<ls-version>-1) unstable; urgency=low

  * Changes listed here

 -- Package Maintainer <[email protected]>  <timestamp>

The timestamp above must be preceeded by two spaces, and must be an RFC 2822 compliant date string, which is most easily produced by issuing the date -R command. Please note that the debian package manager is quite picky on the format of the changelog file. See section 4.4 of the Debian Policy Manual for more details.

Don't forget to commit the changes made to the changelog into the CVS before proceeding.

Creating release tarballs

To create the release tarballs, invoke the distribution script bin/dist.sh, with the release version as its single parameter:

./bin/dist.sh --version <ls-version>

This will create two tarballs in the current directory:

Testing the tarballs

Having broken releases is very annoying, thus it is highly recommended that the release tarballs are tested on a plain vanilla system. To test the tarballs, follow the procedure described in the LiveSupport installation document.

Do not publish tarballs that have not been tested, or are known to be broken.

Creating Debian packages

After the source tarballs have been tested, Debian source and binary packages can be created. To do so, upload the source tarballs to a Debian system, and do the following:

tar xfj livesupport-<ls-version>.tar.bz2
tar xfj livesupport-libraries-<ls-version>.tar.bz2
cd livesupport-<ls-version>
./bin/createDebianPackages.sh -d .. -v <ls-version> -m "Package Maintainer <[email protected]>" -o ..
cd ..

The above command will create the Debain source package files next to the original source tarballs. The script will generate the following files, making up the Debian source package:

livesupport_<ls-version>-1.dsc
livesupport_<ls-version>-1.diff.gz
livesupport_<ls-version>.orig.tar.gz

Based on the source packages, the Debian package management system can build the binaries for the current target platform, provided all the necessary packages required to build are installed on the system. For a list of the necessary packages, please consult the debian/control file in extracted debianized source tree generated below.
Building is best done in an empty directory as follows:

rm -rf debian_build
mkdir debian_build
cd debian_build
dpkg-source -x ../livesupport_<ls_version>-1.dsc
cd livesupport-<ls-version>
dpkg-buildpackage -rfakeroot
cd ../..

The above commands will result in the following debian packages:

livesupport-libs_<ls-version>-1_<arch>.deb
livesupport-station_<ls-version>-1_<arch>.deb
livesupport-studio_<ls-version>-1_<arch>.deb

Tagging the sources

After the tarballs have been tested, the release can be finalized. As a first step, the current state of the LiveSupport version control repository has to be tagged, so that the the very versions in the release can be retrieved at any later date. To tag the repository, issue the following command from the LiveSupport checked out source directory:

cvs tag livesupport_<ls-version>

This will tag the current state of the repository with the tag livesupport_<ls-version>, enabling later retrieval of this specific state. Please note that since CVS does not support dots ('.') in tags, the dots in the version number are replaced by underscore ('_') when tagging. Thus, livesupport-0.9.1 is tagged as livesupport-0_9_1, for example.

Publishing the tarballs

To make the release available to the public, the created tarballs have to be published. This is done by making the files accessible under the LiveSupport project page on SourceForge: http://sourceforge.net/projects/livesupport. Currently, only MDLF support staff have access to publish into this space, so after creating the tarballs, one should contact them personally to publish the files.

Announcing the release

For the public to be aware of the new release, it has to be announced. This is primarily done on the Campware site, but also on other meta-sites, like freshmeat. In particular, the following announcements are made: