At certain stages, the development team releases a version of &app;. The following chapters explain the steps that are performed during this process. 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. Note that in order to perform some of the functions associated with this procedure, you will need to: Obtain a userid by registering with Sourceforge; this userid is represented below as <your_sf_userid> 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. 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. The steps explained apply to both the development and the release branches. For convenience, the examples are based on the development branch. 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. For follow-up releases increase the micro-release-number by one since the last unstable/stable release. For a fresh stable release, increase the minor release number and set the micro-release number to 0. 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 &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). 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. 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'. 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. If the library source code has changed at all since the last release, then increment REVISION (`C:R:A' becomes `C:r+1:A'). If any interfaces have been added, removed, or changed since the last update, increment CURRENT, and set REVISION to 0. If any interfaces have been added since the last public release, then increment AGE. If any interfaces have been removed since the last public release, then set AGE to 0. 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. 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. 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 trinity 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: create a source tar-ball in tgz form unpack this source tar-ball in a separate directory run configure on the unpacked source tar-ball compile and link the configured package compile and link all testcases install the compiled program in a temp directory check that all files are installed uninstall the package from the temp space 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. Update the ChangeLog Add a line with the text * Released x.y.z to the ChangeLog file. 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'. 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. 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 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. 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. 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 Move the tarball to the Sourceforge File Release System 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 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. 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. 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. 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. Prepare for next release Make sure that you increase the project version to the next version. This is derived as follows: 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. 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. The version number in the sandbox is always the version number that is currently being developed (we're a little ahead of ourselves here). 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. When the time has come to create a new stable branch, the following steps have to be performed. Run through all the steps explaind in Creating a new version. The version number used in this description for the stable version is 0.4. Follow the path for a fresh stable release. Create a branch off of the tagged version. The branch name is build by appending the word -branch to the major- and minor-release number of the stable release version. For our example, the branch tag for versions 0.4 is rel-0-4-branch. A complete example with all &cvs; commands can be found in the appendix. 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 rel-0-4-branch. 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 appendix, 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. 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. Since &cvs; does not allow periods inside a tag, we always replace periods (.) with dashes (-) inside a tag. 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. The first file is changed rather often between the version tags. All tags are on different revisions of the file. * (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] 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. * (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] 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. 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. Certain web-sites exist that keep version information about &app;. They need to be updated. The news system for &app; on SourceForge.net: Create a news entry on https://sourceforge.net/projects/kmymoney2. 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. The &app; web-site at http://www.kde-apps.arg/: Add the release notes and update the version and minimum requirements. 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. 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. 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. 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. 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 the previous chapter. 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. 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. 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 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. 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:~> rpmbuild -ba kmymoney.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. 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 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.