Guidelines and HOWTOs/Application Versioning: Difference between revisions

Latest revision as of 17:12, 14 April 2021

Every application has an application version number that regularly has to be increased to distinguish different versions of the application (e.g. features, bug fixes). Not using different version numbers for different releases can lead to a confusing About dialog and lower the quality of the bugs reported, as it will not be clear which version is affected. When an application does not have its own release schedule but is released with as part of the release service (KDE Gear), it can use the version number of the corresponding release service release.

It is the maintainer's duty to take care of increasing the version number regularly for every release. Specifically, there are two possible ways to do that:

Increase the version number by hand for each new release.
Use the same version number as KDE Gear and let the release script update the version number.

In the following, we explain how to use the scripted version numbers from KDE Gear within an application. The release scripts will auto-update the following CMake variables in the toplevel CMakeLists.txt of all applications bundled in the KDE Gear release:

# KDE Application Version, managed by release script
set (RELEASE_SERVICE_VERSION_MAJOR "21")
set (RELEASE_SERVICE_VERSION_MINOR "04")
set (RELEASE_SERVICE_VERSION_MICRO "01")

You can then use them to define the version for your own application based on this.

For example Kate defines in its CMakeLists.txt:

set(RELEASE_SERVICE_VERSION "${RELEASE_SERVICE_VERSION_MAJOR}.${RELEASE_SERVICE_VERSION_MINOR}.${RELEASE_SERVICE_VERSION_MICRO}")

and then use this in the config.h.in:

#define KATE_VERSION "${RELEASE_SERVICE_VERSION}"

This is then passed to the KAboutData:

   /**
    * construct about data for Kate
    */
   KAboutData aboutData(QStringLiteral("kate"), i18n("Kate"), QStringLiteral(KATE_VERSION),
                        i18n("Kate - Advanced Text Editor"), KAboutLicense::LGPL_V2,
                        i18n("(c) 2000-2014 The Kate Authors"), QString(), QStringLiteral("http://kate-editor.org"));

Beside using the full version, you could use only the patch release version ${RELEASE_SERVICE_VERSION_MICRO} to suffix your own version if you don't want to do that manually for each patch release.

Appstream release metadata

Appstream files should also be updated at release time with version numbers and dates of releases.

Appstream wiki page has more info

bugs.kde.org and Appstream versions

If you want to get the bugs.kde.org Bugzilla versions automatically created by the release managers (starting with KDE Applications 17.12.0), your project should use

 project(my_project_name VERSION my_version_name)

Note that this requires cmake_minimum_required(VERSION 3.0). The project() line must be AFTER the cmake_minimum_required() line.

For example Kate would be using

 project(kate VERSION ${RELEASE_SERVICE_VERSION})

At the moment this only works for products whose bugzilla name and repository name are the same, if yours is different and you have a good reason for it, ask in the release team mailing list.

@@ Line 1: / Line 1: @@
-Every application has an application version number that regularly has to be increased to distinguish different versions of the application (e.g. features, bug fixes). Not using different version numbers for different releases can lead to a confusing About dialog and lower the quality of the bugs reported, as it will not be clear which version is affected. When an application does not have its own release schedule but is released with KDE Applications, it can use the version number of the corresponding  KDE Applications release.
+Every application has an application version number that regularly has to be increased to distinguish different versions of the application (e.g. features, bug fixes). Not using different version numbers for different releases can lead to a confusing About dialog and lower the quality of the bugs reported, as it will not be clear which version is affected. When an application does not have its own release schedule but is released with as part of the release service (KDE Gear), it can use the version number of the corresponding release service release.
 It is the maintainer's duty to take care of increasing the version number regularly for every release. Specifically, there are two possible ways to do that:
 # Increase the version number by hand for each new release.
-# Use the same version number as KDE Applications and let the release script update the version number.
+# Use the same version number as KDE Gear and let the release script update the version number.
-In the following, we explain how to use the scripted version numbers from KDE Applications within an application.
+In the following, we explain how to use the scripted version numbers from KDE Gear within an application.
-The release scripts will auto-update the following CMake variables in the toplevel CMakeLists.txt of all applications bundled in the KDE Applications release:
+The release scripts will auto-update the following CMake variables in the toplevel CMakeLists.txt of all applications bundled in the KDE Gear release:
   # KDE Application Version, managed by release script
-  set (KDE_APPLICATIONS_VERSION_MAJOR "15")
+  set (RELEASE_SERVICE_VERSION_MAJOR "21")
-  set (KDE_APPLICATIONS_VERSION_MINOR "04")
+  set (RELEASE_SERVICE_VERSION_MINOR "04")
-  set (KDE_APPLICATIONS_VERSION_MICRO "0")
+  set (RELEASE_SERVICE_VERSION_MICRO "01")
 You can then use them to  define the version for your own application based on this.
@@ Line 18: / Line 18: @@
 For example Kate defines in its CMakeLists.txt:
-  set (KDE_APPLICATIONS_VERSION "${KDE_APPLICATIONS_VERSION_MAJOR}.${KDE_APPLICATIONS_VERSION_MINOR}.${KDE_APPLICATIONS_VERSION_MICRO}")
+  set(RELEASE_SERVICE_VERSION "${RELEASE_SERVICE_VERSION_MAJOR}.${RELEASE_SERVICE_VERSION_MINOR}.${RELEASE_SERVICE_VERSION_MICRO}")
-and then use this in the config.h.cmake:
+and then use this in the config.h.in:
-  #define KATE_VERSION "${KDE_APPLICATIONS_VERSION}"
+  #define KATE_VERSION "${RELEASE_SERVICE_VERSION}"
 This is then passed to the KAboutData:
@@ Line 33: / Line 33: @@
                           i18n("(c) 2000-2014 The Kate Authors"), QString(), QStringLiteral("http://kate-editor.org"));
-Beside using the full version, you could use only the patch release version ${KDE_APPLICATIONS_VERSION_MICRO} to suffix your own version if you don't want to do that manually for each patch release.
+Beside using the full version, you could use only the patch release version ${RELEASE_SERVICE_VERSION_MICRO} to suffix your own version if you don't want to do that manually for each patch release.
-==Bugzilla versions==
+==Appstream release metadata==
-If you want to get the bugzilla versions automatically created by the release managers (starting with KDE Applications 17.12.0), your project should use
+Appstream files should also be updated at release time with version numbers and dates of releases.
+[https://community.kde.org/Guidelines_and_HOWTOs/AppStream#Release_version_numbers_and_dates Appstream wiki page has more info]
+==bugs.kde.org and Appstream versions==
+If you want to get the bugs.kde.org Bugzilla versions automatically created by the release managers (starting with KDE Applications 17.12.0), your project should use
    project(my_project_name VERSION my_version_name)
@@ Line 43: / Line 49: @@
 Note that this requires <tt>cmake_minimum_required(VERSION 3.0)</tt>.  The project() line must be '''AFTER''' the cmake_minimum_required() line.
-For example Okular would be using
+For example Kate would be using
-  project(okular VERSION 1.2.${KDE_APPLICATIONS_VERSION_MICRO})
-and Kate would be using
-   project(kate VERSION ${KDE_APPLICATIONS_VERSION})
+   project(kate VERSION ${RELEASE_SERVICE_VERSION})
 At the moment this only works for products whose bugzilla name and repository name are the same, if yours is different and you have a good reason for it, ask in  the release team mailing list.