path: root/developer-doc/phb/rel-mgmt.docbook

<chapter id="rel-mgmt">
<title>Release Management</title>
<para>
At certain stages, the development team releases a version of &app;. The
following chapters explain the steps that are performed during this process.
</para>

<sect1 id="create-new-source-version">
<title>Creating a new source version</title>
<para>
The process of releasing a new version is to build a source tar-ball archive, verify
that &app; 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.
</para>

<para>
Note that in order to perform some of the functions associated with this procedure, you will need to:
  <para>
    <orderedlist>
      <listitem><para>
      Obtain a userid by registering with Sourceforge; this userid is represented below as &lt;your_sf_userid&gt;
      </para></listitem>
      <listitem><para>
      Be registered as a &kappname; developer; this must be done by a project administrator, the names of which appear on the project home page on Sourceforge.
      </para></listitem>
    </orderedlist>
  </para>
</para>

<para>
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>
<para>
The steps explained apply to both the development and the
release branches. For convenience, the examples are based on the
development branch.
</para>
</note>
</para>

<orderedlist>
<listitem>
<para>Determine the release number which will identify this release.
</para>
<para>
Two types of versions can be created at this time: a <emphasis>follow-up</emphasis> release or a <emphasis>fresh stable</emphasis>
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.
</para>

<para>
  <orderedlist>
    <listitem><para>
    For follow-up releases increase the micro-release-number by one since the last unstable/stable release.    
    </para></listitem>
    <listitem><para>
    For a fresh stable release, increase the minor release number and set the micro-release number to 0.
    </para></listitem>
  </orderedlist>
</para>
</listitem>

<listitem>
<para>Create a new directory for this release
</para>
<para>
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 &app;. 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).
</para>
</listitem>

<listitem>
<para>
Update the text source file for translations.
</para>
<para> This is done from the TLD by running the command:

<programlisting>
<prompt>thb: ~&gt; </prompt><userinput>make package-messages</userinput>
</programlisting>
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
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
  <programlisting>
  make message-stats | ssh &lt;your_sf_userid&gt;@user.sourceforge.net "cat > /home/groups/k/km/kmymoney2/htdocs/translate-stable.xml"
  </programlisting>
You should certainly make sure that this command is run at least once, after all .po files have been committed.
</para>
<para>
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.
</para>
</listitem>

<listitem>
<para>
Check that the version number is correct.
</para>
<para>
In the TLD, check file configure.in.in for the correct version number. A line near the top should look like</para>
  <programlisting>AM_INIT_AUTOMAKE(kmymoney2,0.8.3)</programlisting>
<para>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'.
</para>
</listitem>

<listitem>
<para>
Verify the libtool version number
</para>
<para>Visit all subdirectories that contain a shared library. In the TLD, issue the command
<programlisting>find . -name Makefile.am -exec grep -H LIBVERSION= '{}' \;</programlisting>
(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.
</para>
<para>
  <orderedlist>
    <listitem><para>
      If the library source code has changed at all since the last
      release, then increment REVISION (`C:R:A' becomes `C:r+1:A').
    </para></listitem>

    <listitem><para>
      If any interfaces have been added, removed, or changed since the
      last update, increment CURRENT, and set REVISION to 0.
    </para></listitem>

    <listitem><para>
      If any interfaces have been added since the last public release,
      then increment AGE.
    </para></listitem>

    <listitem><para>
      If any interfaces have been removed since the last public release,
      then set AGE to 0.
    </para></listitem>
  </orderedlist>
</para>

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

<listitem>
<para>
Perform an initial build of the application
</para>
<para>
From the TLD, issue the commands:
</para>

<programlisting>
<prompt>thb: ~&gt; </prompt><userinput>make -f Makefile.dist release</userinput>
<prompt>thb: ~&gt; </prompt><userinput>./configure <emphasis>&lt;any-options-you-need&gt;</emphasis></userinput>
<prompt>thb: ~&gt; </prompt><userinput>make</userinput>
</programlisting>
<para>
This will regenerate all files of the application and rebuild everything automatically.
</para>
</listitem>

<listitem>
<para>
Check the distribution
</para>
<para>
Before doing this, check that all desktop files conform to the freedesktop specification. From the TLD, issue the following command:
<programlisting>
<prompt>thb: ~&gt; </prompt><userinput>find ./kmymoney2 -name '*.desktop' -exec desktop-file-validate {} \;</userinput>
</programlisting>
N.B. Any errors in file x-kmymoney2.desktop can be ignored since trinity does not conform to the specification for this file type.
</para>
<para>
Note: desktop-file-validate is part of the desktop-file-utils package, which may be installed from your distribution repository, or downloaded from
<ulink url="http://www.freedesktop.org/wiki/Software/desktop-file-utils">http://www.freedesktop.org/wiki/Software/desktop-file-utils</ulink> 
</para>
<para>
Then, to check the distribution itself, from the TLD, run the command
 
<programlisting>
<prompt>thb: ~&gt; </prompt><userinput>make distcheck</userinput>
</programlisting>
 
This will do the following things automatically and stop on any error:
</para>

<para>
<orderedlist>
<listitem><para>create a source tar-ball in tgz form</para></listitem>
<listitem><para>unpack this source tar-ball in a separate directory</para></listitem>
<listitem><para>run configure on the unpacked source tar-ball</para></listitem>
<listitem><para>compile and link the configured package</para></listitem>
<listitem><para>compile and link all testcases</para></listitem>
<listitem><para>install the compiled program in a temp directory</para></listitem>
<listitem><para>check that all files are installed</para></listitem>
<listitem><para>uninstall the package from the temp space</para></listitem>
<listitem><para>check that no files are left behind</para></listitem>
</orderedlist>
</para>

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

<listitem>
<para>
Update the ChangeLog
</para>
<para>
Add a line with the text
<programlisting>  * Released x.y.z
</programlisting>
to the ChangeLog file.
</para>
</listitem>

<listitem>
<para>
Commit changes to CVS
</para>
<para>
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'.
</para>
</listitem>

<listitem>
<para>
Tag the version on CVS
</para>
<para>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.
</para>
</listitem>

<listitem>
<para>
Update and optimize the size of the tar-ball
</para>
<para>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:
</para>
  <programlisting>
    <prompt>thb: ~&gt; </prompt><userinput>make dist-bzip2</userinput>
  </programlisting>
</listitem>

<listitem>
<para>Make a checksum of the tarball
</para>
<para>
This can be done with the following command from the TLD
</para>
  <programlisting>
    <prompt>thb: ~&gt; </prompt><userinput>md5sum <emphasis>name-of-tarball.tar.bz2</emphasis> &gt;/home/me/somewheresafe</userinput>
  </programlisting>
<para>This checksum may be used to verify downloaded files at a later stage, and may be added to sourceforge at some future time.
</para>
</listitem>

<listitem>
<para>
Create a Release Note and a release ChangeLog file.
</para>
<para> 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.
</para>
</listitem>

<listitem>
<para>
Upload the tarball to Sourceforge's 'incoming' directory
</para>
<para>
Upload the tar-ball (bz2-version) to ftp://anonymous:&lt;your-email-address&gt;@upload.sourceforge.net:incoming, making sure to use the binary transfer mode.
</para>
<para>
For GUI users: <emphasis>anonymous</emphasis> is the user-name and 
<emphasis>your-email-address</emphasis> is the password.
</para>
<para>
For command line FTP, from the TLD:
<programlisting>
<prompt>thb: </prompt><userinput>ftp</userinput>
<prompt>ftp&gt; </prompt><userinput>open upload.sourceforge.net</userinput>
Connected to osdn.dl.sourceforge.net.
&lt;snip&gt;
<prompt>Name (upload.sourceforge.net:tonyb): </prompt><userinput>anonymous</userinput>
331 Please specify the password.
<prompt>Password:</prompt><userinput>&lt;your_sf_userid&gt;</userinput>
230 Login successful.
Remote system type is UNIX.
Using binary mode to transfer files.
<prompt>ftp&gt; </prompt><userinput>cd /incoming</userinput>
250 Directory successfully changed.
<prompt>ftp&gt; </prompt><userinput>binary</userinput>
200 Switching to Binary mode.
<prompt>ftp&gt; </prompt><userinput>put <emphasis>name-of-tarball.tar.bz2</emphasis></userinput>
<prompt>ftp&gt;</prompt><userinput> quit</userinput>
</programlisting>
</para>
</listitem>

<listitem>
<para>
Move the tarball to the Sourceforge File Release System
</para>
<para>
Next pull the uploaded file into the &app; 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
</para>
<programlisting>
https://sourceforge.net/project/admin/editpackages.php?group_id=4708
</programlisting>
<para>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.</para>
<para>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.</para>
<para>In Step 2, select the kmymoney tarball file and Add.</para>
<para>In Step 3, set Processor to 'platform-independent', File Type to 'source .bz2', and Submit.</para>
<para/>
</listitem>

<listitem>
<para>
Activate tarball on Sourceforge
</para>
<para>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.
</para>
</listitem>

<listitem>
<para>
Update bug lists
</para>
<para>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.
</para>
</listitem>

<listitem>
<para>
Announce the release
</para>
<para>
(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
<link linkend="announce-new-version">Announce new version</link>.
</para>
</listitem>

<listitem>
<para>
Prepare for next release
</para>
<para>
Make sure that you increase the project version to the next version. This is derived as follows:
</para>

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

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

<programlisting>
<prompt>thb: ~&gt; </prompt><userinput>make -f Makefile.dist</userinput>
<prompt>thb: ~&gt; </prompt><userinput>./configure <emphasis>&lt;any-options-you-need&gt;</emphasis></userinput>
<prompt>thb: ~&gt; </prompt><userinput>make</userinput>
</programlisting>
<para>
This will regenerate all files of the application and rebuild everything.
</para>
<para>
Finally, check in the updated configure.in.in to the CVS repository.
</para>

</listitem>

</orderedlist>

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

</sect1>


<sect1 id="create-stable-procedure">
<title>Creating a new stable version</title>
<para>
At a certain time in the project's development cycle, the configuration
manager decides that a feature freeze is necessary to start a new stable
version. The exact dates when this will happen are announced on the
developers mailing list ahead of the event. When the time has come to
freeze the features, a branch will be created as described in this
section. From this time on, the stable release will only be changed to make
the current features of the software more stable. New features are not
introduced to the stable branch but can be developed on the main
branch (unstable) in parallel.

</para>

<para>
When the time has come to create a new stable branch, the following steps
have to be performed.

<orderedlist>
<listitem>
<para>
Run through all the steps explaind in <link linkend="create-stable-example">Creating a new version</link>.
The version number used in this description for the stable version is 0.4.  Follow the path 
for a fresh stable release.
</para>
</listitem>

<listitem><para>
Create a branch off of the tagged version. The branch name is build by appending
the word <emphasis>-branch</emphasis> to the major- and
minor-release number of the stable release version.

For our example, the branch tag for versions 0.4 is
<emphasis>rel-0-4-branch</emphasis>. 
A complete example with all &cvs; commands can be found
<link linkend="create-stable-example">in the appendix</link>.
</para></listitem>

<listitem>
<para>
From this moment on, the developers working on versions 0.4.x must make
sure, that they checkout or update their sandbox using the
tag <emphasis>rel-0-4-branch</emphasis>. This gives them the head revisions of
the files on the 0.4 branch. Omitting this tag information will leave
them on the main branch. The main branch is reserved for the unstable
versions. An example how to keep multiple branches on the same machine is
presented in the <link linkend="multiple-branches">appendix</link>,

<caution>
<para>
The developers really have to
take care from this point on which version they are modifying in their
sandbox. Besides that, it is the developers responsibility to make sure
that bug-fixes are also implemented on the main-branch if applicable.
</para>
</caution>

</para>

<para>
When fixes are applied to the branch, new versions can be created by
incrementing the micro-release thus rel-0-4-1, rel-0-4-2 are the next
tags on the release branch.
</para>

</listitem>
</orderedlist>

<note>
<para>
Since &cvs; does not allow periods inside a tag, we always replace periods
(.) with dashes (-) inside a tag.
</para>
</note>

<para>
The following diagram shows the above example on two specifc files. Each
node represented by an asterisk is labelled with it's revision number
enclosed in parenthesis. If a node has one or more labels attached, then
they are enclosed in brackets. Nodes may exist without a tag. Such
revisions never went into a release neither stable nor unstable but are
valid intermediate steps in the development of the file in question.
</para>

<example>
<title>Revisions on the head of a stable branch</title>
<para>
The first file is changed rather often between the version tags. All tags
are on different revisions of the file.
</para>

<programlisting>


     *     (1.12) [rel-0-3-8]
     |
     *     (1.13)
     |
     *     (1.14) [rel-0-4]
     |\__________________________
     |                           \
     |                            |
     *     (1.15)                 * (1.14.2.1)  [rel-0-4-1]
     |                            |
     *     (1.16) [rel-0-5-0]     * (1.14.2.2)  [rel-0-4-2]

   [HEAD]                  [rel-0-4-branch]


</programlisting>

<para>
The second file is not changed at all between the version
tags. Nevertheless, all tags are available even though now they are on
the same revision 1.2.
</para>

<programlisting>


     *     (1.2) [rel-0-3-8] [rel-0-4]
     |           [rel-0-4-1] [rel-0-4-2] [rel-0-5-0]
     |\__________________________
     |                           \
     |                            |

   [HEAD]                   [rel-0-4-branch]


</programlisting>

</example>


</para>
</sect1>




<sect1 id="announce-new-version">
<title>Announce a new version</title>
<para>
Once the file is visible on the internet, people need to be informed about the new
release. Besides that, the project maintains certain pages, where information about the
current release is kept. These pages need to be updated.
</para>

<sect2 id="announce-new-version-release-system">
<title>Announce new version via File Release System</title>
<para>
The SourceForge File Release System allows to send a short mail about the release of a package to registered
recipients. On the bottom of the page where the uploaded file is moved into the file space of &app; a checkbox
can be activated to send out such a mail. This method should only be used for a new source tar-ball release.
</para>
</sect2>

<sect2 id="update-web-sites">
<title>Update information about release on web-sites</title>
<para>
Certain web-sites exist that keep version information about &app;. They need to be updated.
<orderedlist>
<listitem><para>
The news system for &app; on SourceForge.net:  Create a news entry on https://sourceforge.net/projects/kmymoney2.
</para></listitem>

<listitem><para>
The &app; web-site at http://kmymoney2.sourceforge.net/:  Update all version info
for the stable and development releases and update the links to the source tar-balls.
</para></listitem>

<listitem><para>
The &app; web-site at http://www.kde-apps.arg/: Add the release notes and update the version and minimum requirements.
</para></listitem>

<listitem><para>
The &app; web-site at http://kmymoney2.sourceforge.net/: Update the links to the latest stable and development release.
If you created a fresh stable release, comment the development release entry.
</para></listitem>
</orderedlist>
</para>
</sect2>

<sect2 id="announce-new-version-mail">
<title>Announce new version on mailing lists</title>
<para>
Write a short mail and send it to the developer- and user-mailing list of the project, so that all subscribed
recipients are informed about the new release. Add links to the project web-site and the www.kde-apps.org page
of the project.
</para>
</sect2>

</sect1>






<sect1 id="create-new-bin-version">
<title>Creating a new binary/installable version</title>
<para>
Additionally, installable binary versions of &app; should be provided. Since the installable binary
files differ from distribution to distribution and the generation in general requires the
target platform, the &app; project relies on the help of people not directly involved in
the application development. We greatfully appreciate any help in this area.
</para>

<para>
Multiple formats exist: RPM, DEB, e-builds, PKG just to name a few. Since the distro I use (SuSE) relies on
RPMs, I explain the creation in more detail here. If you can provide similar information about other formats,
we are more than happy to include it in this document. We assume that you follow our licence terms for any
documentation you supply. Please send your docbook formatted files to the developer mailing list.
</para>


<sect2 id="rpm">
<title>Creating an RPM file</title>
<para>
One 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="create-new-source-version">the previous chapter</link>.
</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>

<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="create-new-source-version">tar-ball</link> to this directory.
</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:

<programlisting>

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


</programlisting>

   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:


<programlisting>

  <prompt>thb:~&gt; </prompt><userinput>rpmbuild -ba kmymoney.spec</userinput>


</programlisting>

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>
<programlisting>


  <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;[email protected]&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>


</programlisting>
</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>
<programlisting>

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

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

</programlisting>
</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>
<programlisting>


  <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;[email protected]&gt;"
  <prompt>thb:~&gt; </prompt><userinput></userinput>


</programlisting>

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

</sect1>
</chapter>