Skip to main content
Skip to content
Edit this page See source code Create documentation issue Formatting guidelines Style guidelines

Preparing your software for release

Do this to make a stable or unstable release

This guide applies to all software which is not part of a bigger bundle like Frameworks, Plasma and KDE Gear, which have specific release cycles and release managers.

KDE provides a collection of scripts to facilitate making a new release called releaseme, which will be explained in this page.

Deciding on a stable or unstable release

The first thing to consider when making a release is whether you want to make an unstable release or a stable release. Unstable releases serve to prepare for a stable release, allowing your users to test your software beforehand.

Projects undergoing Incubation are only allowed to make unstable releases. Projects that have passed KDE Review are effectively KDE projects and may do either.

KDE projects typically create up to three unstable releases: alpha, beta, and release candidate. Their versioning scheme ends with .70, .80 and .90 respectively, with the release candidate .90 being the final version before a stable release. See Understanding the software lifecycle for details.

This is not a strict versioning scheme: projects like Plasma and KDE Gear for example use .80 for alpha and .90 for beta, and arbitrary numbers in-between may be used as well. The only requirement is that only numbers be used, as they are more difficult to compute and may cause issues in downstream packaging.

If you want to make an unstable release, you don't need to branch and may skip to the next section, Changes in code. If you plan to make a stable release, follow through with the next sections.

releaseme

KDE has a tool that can be used to semi-automate the release process called releaseme.

It consists of a collection of Ruby scripts for each individual step of the process:

  • branchme
  • tarme
  • tagme
  • logme

You may clone the repository elsewhere and point your PATH to it in order to run the scripts in each directory:

git clone https://invent.kde.org/sdk/releaseme.git
export PATH=$PATH:/path/to/releaseme

Branching

Branching is done to allow the developer to make point releases in the future by using tags. For example, you might:

  • create a 6.5 branch
  • make a 6.5.0 tag based on the 6.5 branch, and thus make a 6.5.0 release
  • later develop on the 6.5 branch
  • make a 6.5.1 tag based on the developed 6.5 branch, and thus make a 6.5.1 release

See Understanding the software lifecycle: The release process in practice for a practical example and diagram.

Branching is an optional step when making stable releases. You should branch when you effectively intend to make new point releases from a stable branch, as the process of making point releases is more complex than just tagging from the master branch. If your master branch doesn't have much feature development, you might prefer to follow the same steps used for unstable releases.

After having set up releaseme, create a new branch with something similar to:

branchme.rb --name 6.5

Changes in code

When you are ready to do a release, make sure the current HEAD in the stable branch has the correct version string set in its source code.

If your project consists of a library, you will also need to set the SOVERSION accordingly to reflect what you want to release.

A good suggestion is to use ecm_setup_version() in your top-level CMakeLists.txt:

cmake_minimum_required(VERSION 3.30)
project(kgraphviewer VERSION 2.4.0)

# ...

find_package(ECM 6.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})
include(ECMSetupVersion)

# ...

ecm_setup_version(${PROJECT_VERSION}
    VARIABLE_PREFIX KGRAPHVIEWER
    SOVERSION ${PROJECT_VERSION_MAJOR}
    VERSION_HEADER "${CMAKE_CURRENT_BINARY_DIR}/config-kgraphviewer.h"
)

This is all that is required for binary applications.

If you are releasing a library, edit the CMakeLists.txt file where the main library target is created with the following:

set_target_properties(kgraphviewerlib
    PROPERTIES
    VERSION ${PROJECT_VERSION}
    SOVERSION ${KGRAPHVIEWER_SOVERSION}
    OUTPUT_NAME kgraphviewer
)

ecm_setup_version() will autogenerate a config-kgraphviewer.h file that looks like this:

Click here to open the config-kgraphviewer.h file
// This file was generated by ecm_setup_version(): DO NOT EDIT!

#ifndef KGRAPHVIEWER_VERSION_H
#define KGRAPHVIEWER_VERSION_H

#define KGRAPHVIEWER_VERSION_STRING "2.4.0"
#define KGRAPHVIEWER_VERSION_MAJOR 2
#define KGRAPHVIEWER_VERSION_MINOR 4
#define KGRAPHVIEWER_VERSION_PATCH 0
#define KGRAPHVIEWER_VERSION ((2<<16)|(4<<8)|(0))

#endif

The file can then be included in your main.cpp, making the KGRAPHVIEWER_VERSION define and others available in your code. This can be used, for example, in the KAboutData project version in your application. You can also install this file (useful for libraries to do feature-detection based on the version number).

Feature freeze and freeze for translators

To prevent regressions early before a release, you will have to perform a feature freeze on the branch. From this point on, no new features should be introduced to the stable branch.

Additionally, because your project will ship translations, you will have to perform a string freeze, that is, making no changes to any translatable strings.

Before a release, you'll need to give translators a notification about the upcoming new version.

If you created a stable branch, make a merge request to repo-metadata to set the "stable i18n branch" to the new stable branch.

Send an email about one month before the release or so to the KDE i18n-doc mailing list kde-i18n-doc@kde.org notifying translators of the string freeze.

This is to ensure that translators have some time to localize your software before release. If you do need a string changed, ask the translators for a string freeze exception.

Other feature branches will always be unfrozen, and any kind of strings or features can be changed or added.

If the release is going to be unstable, the string freeze (and all pertinent steps) may be performed on the master branch as well until the day of release.

Creating a tarball

A tarball is an archive containing the source code matching the tag, used by downstreams to reproducibly build your software.

To create the tarball, you will need to generate your own GPG key, which can be easily done with Kleopatra. The subsequent steps will fail if you do not have a GPG key.

Before using releaseme, you will need to make a merge request to repo-metadata changing your project's i18n.json file to point trunk to the master branch and stable to the created stable branch (if you are planning on making point releases). These will be considered origins for releaseme.

After having set up releaseme, create a new tarball with something similar to:

tarme.rb --origin stable --version 6.5.0

If you are not planning to make point releases, you may instead use the trunk origin:

tarme.rb --origin trunk --version 6.5.0

Tagging

After having set up releaseme, create a new tag with something similar to:

tagme.rb --version 6.5.0

Publishing

The instructions on uploading the tarball to the KDE are present in https://upload.kde.org:

kate ftp://upload.kde.org/README

This domain is used only for uploading tarballs. You may upload the tarball with something like:

curl -T "myapp-0.1.tar.xz{,.sig}" ftp://upload.kde.org/incoming/

Or:

echo put myapp-0.1.tar.xz | ftp ftp://upload.kde.org/incoming/
echo put myapp-0.1.tar.xz.sig | ftp ftp://upload.kde.org/incoming/

Then, file a sysadmin ticket to notify about the upload and to provide the checksums for verification: go.kde.org/u/systickets. The tarball will be moved from the incoming folder to the correct place under download.kde.org, which is where downstreams like Linux distributions will download the sources of your application.

Aftersteps

The new version should be added to the list of available versions to the component/product. If you don't have enough permissions, create a sysadmin ticket for that, or ask this a part of the ticket created when uploading the tarballs.

Release announcement

Once the sysadmins moved the tarball, you can announce the release. First send an e-mail to kde-announce-apps@kde.org and your project's mailing list(s). The mail can be short and link to a longer announcement blog post or news item. If you write a detailed blog post, make sure that that your blog/site is aggregated on planet.kde.org. This can be done on the planet-kde-org repository.

You should include the full fingerprint to the GPG key used to sign the tar and tags in your announcement e-mail. Upload your key to openPGP key servers using gpg2 --send-keys <fingerprint>.

Ideally you also want to sign your email with the key in question to prove that you have control over the key.

Previous
Passing KDE Review