This document describes the process of releasing a new version of
Campcaster. 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 Campcaster 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 Campcaster sources
checking the distribution script
updating release version and changelog
creating release tarballs
testing the tarballs
creating Debian packages
tagging the sources
publishing the tarballs
announcing the release
Getting Campcaster sources
It is assumed that the person doing the release has a read/write access
to the Campcaster 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:
the release contains exactly the files that are in the version
control system
there are no generated files in the release
To get a fresh copy of the Campcaster repository, execute the
following in an empty directory:
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.
You need to update the version information in the following files:
You can change the “-1” part (to “-2” or “-0distro1” etc). Note that the
<version> string, which will be referred to below,
is without this extension; the extension will be read from the
changelog file by the Debian packaging scripts.
The <timestamp> 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 Subversion
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 <version>
This will create two tarballs in the parent of the current directory:
campcaster-<version>.tar.bz2
campcaster-libraries-<version>.tar.bz2
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 Campcaster 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, install the packages needed to install Campcaster,
plus two more needed for the build process: debhelper and
fakeroot. Then do the following:
tar xfj campcaster-<version>.tar.bz2
tar xfj campcaster-libraries-<version>.tar.bz2
cd campcaster-<version>
./bin/createDebianPackages.sh -d .. -v <version> -o .. -m "Joe Maintainer <[email protected]>"
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:
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 control file
in the extracted debianized source tree generated below
(build/campcaster-<version>/debian/control).
Building is best done in an empty directory as follows:
rm -rf /opt/campcaster
rm -rf build
mkdir build
cd build
dpkg-source -x ../campcaster_<version>-1.dsc
cd campcaster-<version>
sudo dpkg-buildpackage &> ../build.log
cd ..
The above commands will result in the following debian packages:
For users to be able to install the packages using apt-get
or Synaptic etc., they need to be uploaded to the Campware
package repository on code.campware.org.
To do this, you need to do the following, as real root (sudo is not enough):
Copy the three package files to the
/var/www/ubuntu/packages/dapper/<arch> directory
on code.campware.org. If the directory contained earlier
versions of the packages, you can delete those.
Generate the package listing:
cd /var/www/ubuntu
apt-ftparchive packages packages/dapper/<arch> | gzip -9c > dists/dapper/main/binary-<arch>/Packages.gz
For other releases, like edgy, feisty, etc, replace ‘dapper’ accordingly
everywhere, of course.
Tagging the sources
After the tarballs have been tested, the release can be finalized. As a
first step, the current state of the Campcaster 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:
This will tag the current state of the repository with the tag campcaster-<version>,
enabling later retrieval of this specific state.
Updating Trac
Add the new version number to the Version pull-down menu in Trac by
executing
trac-admin /usr/local/trac-projects/campcaster version add <version>
on code.campware.org.
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
Campcaster project page on SourceForge:
http://sourceforge.net/projects/campcaster.
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: