<chapter id="rel-mgmt">
<title>Release Management</title>
<para>
Whenever the project development team decides to build a new release, it
follows the procedure described in <link linkend="create-new-version">
Creating a new version</link>. This procedure will mark the required
files for that version in the repository.
</para>

<para>
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.
</para>

<sect1 id="tar-ball">
<title>Tar Ball</title>
<para>
The first step is to produce a source tar-ball archive. Two possible ways
exist to do that

<itemizedlist>
<listitem><para>from within KDevelop</para></listitem>
<listitem><para>from the shell command line</para></listitem>
</itemizedlist>

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).
</para>

<sect2 id="tar-ball-kdevelop">
<title>KDevelop</title>
<para>
If you are used to the KDevelop integrated development environment (IDE)
you just select the <command>Project/Make distribution/Source-tgz</command>
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)
</para>
</sect2>

<sect2 id="tar-ball-shell">
<title>Shell</title>
<para>
If you are using the shell to execute commands, you might execute
<command>make dist</command> from the top directory of the project. This
leads to the same result, the kmymoney2-0.4pre2.tar.gz file.
</para>
</sect2>

<sect2 id="tar-ball-optimize">
<title>Size optimization for tar-ball</title>
<para>
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.

<screen>

  <prompt>thb:~&gt; </prompt><userinput>gunzip kmymoney2-0.4pre2.tar.gz</userinput>
  <prompt>thb:~&gt; </prompt><userinput>bzip2 kmymoney2-0.4pre2.tar</userinput>


</screen>

This results in a file called kmymoney2-0.4pre2.tar.bz2 which is the final
version of the source tar ball.
</para>
</sect2>
</sect1>

<sect1 id="rpm">
<title>Creating an RPM file</title>
<para>
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 <link
linkend="tar-ball">the previous chapter</link>. Either version (GZIP or
BZIP2) will work.
</para>

<para>
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.
</para>

<para>
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.
</para>

<sect2 id="rpm-tar-ball">
<title>Copying the tar-ball to the RPM structure</title>
<para>
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 <link 
linkend="tar-ball">tar-ball</link> to this directory. Either version
(GZIP or BZIP2) will be ok.
</para>
</sect2>

<sect2 id="rpm-test-building">
<title>Test building</title>
<para>
<!-- taken from RPM Howto (start) -->
   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:

<screen>

  <prompt>thb:~&gt; </prompt><userinput>diff -uNr dirname.orig dirname &gt; ../SOURCES/dirname-distroname.patch</userinput>


</screen>

   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.
<!-- taken from RPM Howto (end) -->
<note>
<para>
This section has been copied from the RPM-Howto and adapted where necessary
</para>
</note>
</para>
</sect2>

<sect2 id="rpm-specfile">
<title>Setting up the SPEC file</title>
<para>
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. 
</para>
</sect2>

<sect2 id="rpm-build-package">
<title>Building the package</title>
<para>
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:


<screen>

  <prompt>thb:~&gt; </prompt><userinput>rpm -ba kmymoney2.xxx.spec</userinput>


</screen>

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.
<note>
<para>
More details about this process and a description on the available options
can be found in the RPM-Howto.
</para>
</note>
</para>
</sect2>

<sect2 id="rpm-test">
<title>Testing the package</title>
<para>
<!-- taken from RPM Howto (start) -->
   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.
</para>

<para>
   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.
<!-- taken from RPM Howto (end) -->

<note>
<para>
This section has been copied from the RPM-Howto and adapted where necessary
</para>
</note>
</para>
</sect2>

<sect2 id="rpm-sign">
<title>Signing the package</title>
<para>
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.
</para>

<para>
 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:

<itemizedlist>
<listitem>
   <para>Always distribute both files together</para>
</listitem>
<listitem>
   <para>
      Make your public key available on e.g.
      <ulink url="http://www.keyserver.net/">http://www.keyserver.net</ulink>.
   </para></listitem>
</itemizedlist>

The following example shows the command sequence necessary to create an
ASCII armored signature.
</para>

<para>
<screen>


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

  Enter passphrase: <userinput>I WON'T TELL YOU MY PASSPHRASE ;-)</userinput>
  <prompt>thb:~&gt; </prompt><userinput></userinput>


</screen>
</para>

<para>
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. <command>THIS IS NOT THE REAL SIGNATURE, EVEN IF IT LOOKS LIKE
IT</command>. 
</para>

<para>
<screen>

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

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

</screen>
</para>

<para>
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. <ulink
url="http://www.keyserver.net/">http://www.keyserver.net</ulink>) into his
keyring. The verification is performed using &GPG; as the following example
shows:
</para>


<para>
<screen>


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


</screen>

<note>
<para>
Besides signing the RPM package, the SRPM (Source-RPM) package should be
signed as well.
</para>
</note>
</para>
</sect2>

</sect1>
</chapter>
