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 <your_sf_userid>
</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:
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 <your_sf_userid>@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>
<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
(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.
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>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:<your-email-address>@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>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.
