Home 

Chapter 2. Release Management

Table of Contents

Creating a new source version
Creating a new stable version
Announce a new version
Announce new version via File Release System
Update information about release on web-sites
Announce new version on mailing lists
Creating a new binary/installable version
Creating an RPM file
Copying the tar-ball to the RPM structure
Test building
Setting up the SPEC file
Building the package
Testing the package
Signing the package

At certain stages, the development team releases a version of KMyMoney. The following chapters explain the steps that are performed during this process.

Creating a new source version

The process of releasing a new version is to build a source tar-ball archive, verify that KMyMoney can be built from it and upload it to the SourceForge File Release System. This chapter explains the steps of making sure that the version numbers are set correctly, creating the source tar-ball, tagging the repository etc.

Note that in order to perform some of the functions associated with this procedure, you will need to:

  1. Obtain a userid by registering with Sourceforge; this userid is represented below as <your_sf_userid>

  2. Be registered as a KMyMoney developer; this must be done by a project administrator, the names of which appear on the project home page on Sourceforge.

The first few steps of the release process should be taken some time in advance of the anticipated release date, in order to give translators a chance to 'do their thing'. The length of time required will depend on how many translatable strings have been changed since the previous release, but something like two weeks for a minor release should suffice.

Note

The steps explained apply to both the development and the release branches. For convenience, the examples are based on the development branch.

  1. Determine the release number which will identify this release.

    Two types of versions can be created at this time: a follow-up release or a fresh stable release. The follow-up release is based on a previous release with the same major and minor release number. The fresh stable release starts a new major and minor release number pair. In the latter case, the major and minor release numbers on the development branch in CVS are also adjusted. More details below.

    1. For follow-up releases increase the micro-release-number by one since the last unstable/stable release.

    2. For a fresh stable release, increase the minor release number and set the micro-release number to 0.

  2. Create a new directory for this release

    Create a new directory specifically for the release process, something like /home/me/distkmm, which will ensure that the following steps are not contaminated by other, existing versions of KMyMoney. From this directory, check out a copy of the app from the CVS branch which forms the basis of this release, e.g. for 0.8.2, the branch will be rel-0-8-branch. The checkout process will create a sub-directory called kmymoney2. This is referred to subsequently as the TLD (top level directory).

  3. Update the text source file for translations.

    This is done from the TLD by running the command:

    thb: ~> make package-messages
    

    This will create the file kmymoney2.pot in TLD/po, and will merge all new and changed messages into the various translation files in the same directory. These files (kmymoney2.pot and *.po) should be committed to the appropriate branch of CVS. Also, an announcement should be made on the translator's mailing list that these are ready for updating, and mentioning a date a few days before the proposed release date as a deadline for translations to be submitted.

    At this point also, a 'string freeze' for the base release should be declared on the developer's list. From now on until the release is complete, the only changes which should be committed to the CVS branch should be fixes which do not change translatable strings, and updated .po files submitted by translators.

    As each .po file is committed, it is desirable to update the translation statistics on the project web site. This can be performed with the command

      make message-stats | ssh <your_sf_userid>@user.sourceforge.net "cat > /home/groups/k/km/kmymoney2/htdocs/translate-stable.xml"
      
    You should certainly make sure that this command is run at least once, after all .po files have been committed.

    Once the anticipated release date is reached, you should make sure that your sandbox is up-to-date. This is probably best achieved by deleting the directory created in step 2, and re-creating it by a full CVS checkout as described there.

  4. Check that the version number is correct.

    In the TLD, check file configure.in.in for the correct version number. A line near the top should look like

    AM_INIT_AUTOMAKE(kmymoney2,0.8.3)

    If the last digits don't match the release number, then change them and commit your change to the repository with the message 'Bumped to release x.y.z'.

  5. Verify the libtool version number

    Visit all subdirectories that contain a shared library. In the TLD, issue the command

    find . -name Makefile.am -exec grep -H LIBVERSION= '{}' \;
    (Note that the space before the backslash is necessary.) For each match, check whether the code or interface of the shared library has been changed since the last release. If so, modify the LIBVERSION setting in each Makefile.am according to the following recipe, where the LIBVERSION setting controls the libtool versioning system for shared libraries. It is constructed out of the triplet CURRENT:REVISION:AGE.

    1. If the library source code has changed at all since the last release, then increment REVISION (`C:R:A' becomes `C:r+1:A').

    2. If any interfaces have been added, removed, or changed since the last update, increment CURRENT, and set REVISION to 0.

    3. If any interfaces have been added since the last public release, then increment AGE.

    4. If any interfaces have been removed since the last public release, then set AGE to 0.

    Caution

    Make sure to modify the numbers in coordination with changes on the release- and development branch. It could well be, that the REVISION must be incremented more than 1 if it has been changed on the other branch as well.

  6. Perform an initial build of the application

    From the TLD, issue the commands:

    thb: ~> make -f Makefile.dist release
    thb: ~> ./configure <any-options-you-need>
    thb: ~> make
    

    This will regenerate all files of the application and rebuild everything automatically.

  7. Check the distribution

    Before doing this, check that all desktop files conform to the freedesktop specification. From the TLD, issue the following command:

    thb: ~> find ./kmymoney2 -name '*.desktop' -exec desktop-file-validate {} \;
    
    N.B. Any errors in file x-kmymoney2.desktop can be ignored since kde3 does not conform to the specification for this file type.

    Note: desktop-file-validate is part of the desktop-file-utils package, which may be installed from your distribution repository, or downloaded from http://www.freedesktop.org/wiki/Software/desktop-file-utils

    Then, to check the distribution itself, from the TLD, run the command

    thb: ~> make distcheck
    
    This will do the following things automatically and stop on any error:

    1. create a source tar-ball in tgz form

    2. unpack this source tar-ball in a separate directory

    3. run configure on the unpacked source tar-ball

    4. compile and link the configured package

    5. compile and link all testcases

    6. install the compiled program in a temp directory

    7. check that all files are installed

    8. uninstall the package from the temp space

    9. check that no files are left behind

    Make sure that everything builds correctly. If errors occur, correct them and rerun make distcheck. Once everything is ok, a respective message, that the tar-ball is ready for distribution is shown at the end of make distcheck.

  8. Update the ChangeLog

    Add a line with the text

      * Released x.y.z
    
    to the ChangeLog file.

  9. Commit changes to CVS

    Commit the updated ChangeLog file, and any Makefiles updated in step 5 to the CVS repository before you proceed with the next step. Use the message 'Released x.y.z'.

  10. Tag the version on CVS

    From the TLD, issue the command 'cvs tag rel-x-y-z', where x-y-z is the release number with dots replaced by dashes.

  11. Update and optimize the size of the tar-ball

    As the content has changed since the tar-ball was created in step 7, we need to re-create it. Create a more compressed version using the command:

        thb: ~> make dist-bzip2
      
  12. Make a checksum of the tarball

    This can be done with the following command from the TLD

        thb: ~> md5sum name-of-tarball.tar.bz2 >/home/me/somewheresafe
      

    This checksum may be used to verify downloaded files at a later stage, and may be added to sourceforge at some future time.

  13. Create a Release Note and a release ChangeLog file.

    The former should contain a brief description of the release and any new features which have been added. The latter should be a tidied-up version of the application ChangeLog file, though any purely internal changes may be omitted.

  14. Upload the tarball to Sourceforge's 'incoming' directory

    Upload the tar-ball (bz2-version) to ftp://anonymous:<your-email-address>@upload.sourceforge.net:incoming, making sure to use the binary transfer mode.

    For GUI users: anonymous is the user-name and your-email-address is the password.

    For command line FTP, from the TLD:

    thb: ftp
    ftp> open upload.sourceforge.net
    Connected to osdn.dl.sourceforge.net.
    <snip>
    Name (upload.sourceforge.net:tonyb): anonymous
    331 Please specify the password.
    Password:<your_sf_userid>
    230 Login successful.
    Remote system type is UNIX.
    Using binary mode to transfer files.
    ftp> cd /incoming
    250 Directory successfully changed.
    ftp> binary
    200 Switching to Binary mode.
    ftp> put name-of-tarball.tar.bz2
    ftp> quit
    

  15. Move the tarball to the Sourceforge File Release System

    Next pull the uploaded file into the KMyMoney section of the File Release System on SourceForge so that the file will be visible to everyone on the internet. To do that, load the following URL in your browser

    https://sourceforge.net/project/admin/editpackages.php?group_id=4708
    

    At the bottom of the page, click on the 'Edit releases' link. If the release (x.y.z) you've built doesn't appear in the list, go back a page and click on the 'Add release' link to add it, then return to 'Edit releases', then click the 'Edit this release' link for your release.

    In Step 1 of the page, set the status to Hidden for now, paste the Release Notes and ChangeLog into the appropriate boxes and Submit.

    In Step 2, select the kmymoney tarball file and Add.

    In Step 3, set Processor to 'platform-independent', File Type to 'source .bz2', and Submit.

  16. Activate tarball on Sourceforge

    Once you are happy that the tarball was uploaded okay, and the release announcements are all correct, enter the File Release system again, and set the status to Active.

  17. Update bug lists

    If the ChangeLog indicates that any Sourceforge or KDE bugs have been fixed in this release, log on to the respective bug sites and ensure that they are marked as closed.

  18. Announce the release

    (At this point, you may wish to wait a few hours to allow Sourceforge to populate its mirror sites, thus avoiding complaints to the mailing lists.) Announce the presence of the source tar-ball archive as described in Announce new version.

  19. Prepare for next release

    Make sure that you increase the project version to the next version. This is derived as follows:

    1. After a follow-up release, increase the micro-release-number by one, e.g. if the release you are currently working on is called 0.7.3 then set the release number to 0.7.4.

    2. After a fresh stable release, increase the minor release number and set the micro-release number to 0, e.g.if the release you are currently working on is called 0.6 then set the release number to 0.7.0.

    Make the appropriate changes to configure.in.in as described in step 4 above. From the TLD, issue the commands:

    thb: ~> make -f Makefile.dist
    thb: ~> ./configure <any-options-you-need>
    thb: ~> make
    

    This will regenerate all files of the application and rebuild everything.

    Finally, check in the updated configure.in.in to the CVS repository.

Note

The version number in the sandbox is always the version number that is currently being developed (we're a little ahead of ourselves here).