# Release Management

Whenever the project development team decides to build a new release, it follows the procedure described in Creating a new version. This procedure will mark the required files for that version in the repository.

Additionally, it is necessary to provide an installable versions of &app;. The following chapters explain how to produce the various files. They all assume that you have checked out a version of the project using a release tag.

## Tar Ball

The first step is to produce a source tar-ball archive. Two possible ways exist to do that

- from within KDevelop

- from the shell command line

The name for the tar-ball archive is derived from the projects name and the respective version. For this example I use the version 0.4pre2 which leads to a base filename of kmymoney2-0.4pre2.tar with various endings according to the compression used (gzip or bzip2).

### KDevelop

If you are used to the KDevelop integrated development environment (IDE) you just select the `Project/Make distribution/Source-tgz` menu entry which will create the file for you in the projects top directory with an appropriate name (e.g. kmymoney2-0.4pre2.tar.gz)

### Shell

If you are using the shell to execute commands, you might execute `make dist` from the top directory of the project. This leads to the same result, the kmymoney2-0.4pre2.tar.gz file.

### Size optimization for tar-ball

The above described methods deliver a GZIPed tar-archive. As BZIP2 gives a better compression ratio, you might want to transform the archive to a BZIP2 compressed version with the following commands.

      thb:~> gunzip kmymoney2-0.4pre2.tar.gz
      thb:~> bzip2 kmymoney2-0.4pre2.tar

This results in a file called kmymoney2-0.4pre2.tar.bz2 which is the final version of the source tar ball.

## Creating an RPM file

Another possibility to distribute the program is to use the Red-Hat Package manager (RPM) format. In order to be able to create such a package for &app;, you need to have a source tar-ball as described in the previous chapter. Either version (GZIP or BZIP2) will work.

The RPM system uses a directory structure which for my system - a SuSE distribution - is located in /usr/src/packages. This may be different on your system. The location can be configured in /etc/rpmrc. I will refer to this directory as the 'RPM base directory' in the remainder of this document.

The RPM base directory has a set of subdirectories. They all serve a specific purpose. For us, the directories SOURCES, SPECS, SRPMS and RPMS are important. RPMS is further divided into directories for specific CPU architectures (e.g. i386, i486, ppc, etc.). In the remainder of this document, I will use the names of these directories without mentioning the RPM base directory.

### Copying the tar-ball to the RPM structure

The first thing that needs to be done is to copy the tar-ball to a defined place where the RPM tool will look for it. For this purpose the SOURCES directory is used. Move or copy your tar-ball to this directory. Either version (GZIP or BZIP2) will be ok.

### Test building

The first thing you'll probably want to do is get the source to build cleanly without using RPM. To do this, unpack the sources, and change the directory name to $NAME.orig. Then unpack the source again. Use this source to build from. Go into the source directory and follow the instructions to build it. If you have to edit things, you'll need a patch. Once you get it to build, clean the source directory. Make sure and remove any files that get made from a configure script. Then cd back out of the source directory to its parent. Then you'll do something like:

      thb:~> diff -uNr dirname.orig dirname > ../SOURCES/dirname-distroname.patch

This will create a patch for you that you can use in your spec file. Note that the "distro-name" that you see in the patch name is just an identifier. You might want to use something more descriptive like "MDK9" or "RPM8" to describe why you had to make a patch. It's also a good idea to look at the patch file you are creating before using it to make sure no binaries were included by accident.

This section has been copied from the RPM-Howto and adapted where necessary

#### Setting up the SPEC file

The next step is to create an RPM SPEC file for the specific distribution. The contents may vary between distribution and that is where your knowledge is required. An example for an RPM SPEC file is contained in appendix ??. It will work on SuSE 8.1 directly. More details on howto setup a SPEC file including an explanation of the various sections, commands and options is contained in the RPM-Howto.

#### Building the package

Once you have the spec file it's time to try and build your package. The usual way to do this is using the following command:

      thb:~> rpm -ba kmymoney2.xxx.spec

Once the command finishes successfully, you have a source RPM in SRPMS and a binary RPM for your distribution in one of the subdirectories of RPMS.

More details about this process and a description on the available options can be found in the RPM-Howto.

#### Testing the package

Once you have a source and binary rpm for your package, you need to test it. The easiest and best way is to use a totally different machine from the one you are building on to test. After all, you've just done a lot of make install's on your own machine, so it should be installed fairly well.

You can do an rpm -e packagename on the package to test, but that can be deceiving because in building the package, you did a make install. If you left something out of your file list, it will not get uninstalled. You'll then reinstall the binary package and your system will be complete again, but your rpm still isn't. Make sure and keep in mind that just because you do a rpm -ba package, most people installing your package will just be doing the rpm -i package. Make sure you don't do anything in the build or install sections that will need to be done when the binaries are installed by themselves.

This section has been copied from the RPM-Howto and adapted where necessary

#### Signing the package

Once you are confident with the RPM package, it is a good idea to sign it with your secret &GPG; key before you distribute it. Signing the package allows any recipient of the package to verify that it has not been altered by an unauthorized party.

Signing will create a separate file that contains the electronic signature for the RPM file. In order to allow any recipient to verify the signature, two things have to be kept in mind:

- Always distribute both files together

- Make your public key available on e.g. http://www.keyserver.net.

The following example shows the command sequence necessary to create an ASCII armored signature.

      thb:~> gpg -b -a kmymoney2-0.5.1-1.i386.rpm
      You need a passphrase to unlock the secret key for
      user: "Thomas Baumgart <thb@net-bembel.de>"
      1024-bit DSA key, ID B75DD3BA, created 2001-06-23

      Enter passphrase: I WON'T TELL YOU MY PASSPHRASE ;-)
      thb:~>

Once you have entered the correct passphrase the signature file will be created under the name kmymoney2-0.5.1-1.i386.rpm.asc. As an example, I include it here. `THIS IS NOT THE REAL SIGNATURE, EVEN IF IT LOOKS LIKE IT`.

       -----BEGIN PGP SIGNATURE-----
       Version: GnuPG v1.0.7 (GNU/Linux)

       iD8DBQA+E1DInFnbQLdd07oRAmFQAKDV0I9nzxGEIh1Mx/tzoZ4J3Iyt6gCfTXl1
       LrISXXgD6xELWZlO+NsWbLw=
       =qJIP
       -----END PGP SIGNATURE-----

These two files, the RPM and the signature, should be distributed to the public. The receiver of these two files can now verify if the RPM file is the one you signed or has been modified. Therefor, he needs your public key which he gets from one of the public key servers (e.g. http://www.keyserver.net) into his keyring. The verification is performed using &GPG; as the following example shows:

      thb:~> gpg --verify kmymoney2-0.5.1-1.i386.rpm.asc
      gpg: Signature made Wed 01 Jan 2003 09:16:37 PM CET using DSA key ID B75DD3BA
      gpg: Good signature from "Thomas Baumgart <thb@net-bembel.de>"
      thb:~>

Besides signing the RPM package, the SRPM (Source-RPM) package should be signed as well.