View source for ReleasingSoftware

This page documents the steps to release KDE extragear software packages.

== Sanity Checklist ==

Stuff your project should have before beta or final release:
* Have completed (or at least be going through) [https://community.kde.org/Policies/Application_Lifecycle review in kdereview] or [https://community.kde.org/Incubator Incubator]
* A full copy of all the licences used, typically GPL 2 in a file called COPYING [https://community.kde.org/Policies/Licensing_Policy Licensing Policy]
* A [https://techbase.kde.org/Development/Tutorials/Localization/i18n_Build_Systems#Writing_a_Messages.sh_script Messages.sh file] which extracts all the i18n() translations
* An appinfo.xml file with AppStream data [https://community.kde.org/Guidelines_and_HOWTOs/AppStream AppStream Guidelines]
* A screenshot in [https://phabricator.kde.org/source/websites-product-screenshots/ product-screenshots]
* Check [https://build.kde.org/ KDE CI] and other CIs such as [http://build.neon.kde.org/ KDE neon] that it compiles successfully
* Documentation appropriate to the project: API documentation, user documentation (including docbook or other format documented by the Documentation team)

== Branching ==

Before you create a release, branch it off of master. The name should be "$MAJOR.$MINOR" or similar, i.e. "1.2". This branch will be called "stable branch" in the text below. Push the branch to the remote repository.

<source lang="bash">
git branch -b 1.2
git push --set-upstream origin 1.2
</source>

You can also branch after making a tar using releaseme's branchme.rb script

Whenever you make a new stable branch you must e-mail [https://mail.kde.org/mailman/listinfo/kde-i18n-doc kde-i18n-doc] to ask for translations to also be branched and repo-metadata to be updated.

== Freezing ==

To prevent regressions early before a release, it is suggested to announce and enforce a "feature-freeze". From this point on, no new features should be introduced to the stable branch.

Before a release, you'll need to give translators a notification about the upcoming new version. Update kde:sysadmin/repo-metadata (read the README.md first), set the "stable i18n branch" to the stable branch. Then write an email about one month before the release or so to the translators at  on KDE i18n-doc <kde-i18n-doc@kde.org> . At this point, do not do any changes to translated strings, i.e. consider your branch to be "string-frozen". If you do need a string changed, ask the translators for a string-freeze exception.

Note: The master branch and other feature branches will always be unfrozen, and any kind of strings or features can be changed/added.

== Versioning in source code and libraries ==

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 as well as the SOVERSION etc., to reflect what you want to release.

A good suggestion is to have something like this in your top-level CMakeLists.txt:

<source lang="cmake">
set(KGRAPHVIEWER_VERSION_MAJOR "2")
set(KGRAPHVIEWER_VERSION_MINOR "1")
set(KGRAPHVIEWER_VERSION_PATCH "90")
set(KGRAPHVIEWER_SOVERSION "${KGRAPHVIEWER_VERSION_MAJOR}")
set(KGRAPHVIEWER_LIB_VERSION "${KGRAPHVIEWER_VERSION_MAJOR}.${KGRAPHVIEWER_VERSION_MINOR}")
configure_file (config-kgraphviewer.h.cmake ${CMAKE_CURRENT_BINARY_DIR}/config-kgraphviewer.h )

#usage somewhere in cmake for a library:
set_target_properties(kgraphviewerlib PROPERTIES VERSION ${KGRAPHVIEWER_LIB_VERSION} SOVERSION ${KGRAPHVIEWER_SOVERSION} OUTPUT_NAME kgraphviewer )
</source>

The config-kgraphviewer.h looks like this:

<source lang="cpp">
/* config-kgraphviewer.h.  Generated by cmake from config.-kgraphviewer.h.cmake */

#ifndef CONFIG_KGRAPHVIEWER_H
#define CONFIG_KGRAPHVIEWER_H

#include <kdeversion.h>

#define KGRAPHVIEWER_MAJOR_VERSION @KGRAPHVIEWER_VERSION_MAJOR@
#define KGRAPHVIEWER_MINOR_VERSION @KGRAPHVIEWER_VERSION_MINOR@
#define KGRAPHVIEWER_PATCH_VERSION @KGRAPHVIEWER_VERSION_PATCH@

#define KGRAPHVIEWER_VERSION_STR "@KGRAPHVIEWER_VERSION_MAJOR@.@KGRAPHVIEWER_VERSION_MINOR@.@KGRAPHVIEWER_VERSION_PATCH@"

#define KGRAPHVIEWER_VERSION KDE_MAKE_VERSION(@KGRAPHVIEWER_VERSION_MAJOR@, @KGRAPHVIEWER_VERSION_MINOR@, @KGRAPHVIEWER_VERSION_PATCH@)

#endif // CONFIG_KGRAPHVIEWER_H
</source>

Then you can include the generated config-kgraphviewer.h in e.g. your main.cpp and use the KGRAPHVIEWER_VERSION_STR define and similar. You can also install this file (useful for libraries to do feature-detection based on the version number).

NOTE: Don't forget to also increase the version number in master, after you branched off. I.e. as soon as you created a "1.2" branch, ensure master's source code uses a version string such as "1.2.80" which is analogous to 1.3 Alpha 1. "1.2.90" would be 1.3 Beta 1.

== Creating a Tarball ==

The kde:releaseme scripts help with that.

First check you have a working gpg2 install and a key set up which can do the digital signature:
<source lang="bash">
echo test > test.text; gpg2 --armor --detach-sign -o test.text.sig test.text
</source>

If that works create the tar:

<source lang="bash">
./tarme.rb --version 0.1 --origin stable myapp
</source>

This will create myapp-0.1.tar.xz and its digital signature myapp-0.1.tar.xz.sig

--origin can also be trunk.  It will use the Git branch set in trunk_kf5 or stable_kf5 in the i18n.json file in your project's [https://phabricator.kde.org/source/sysadmin-repo-metadata/ repo_metadata]

== Uploading the Tar ==

Read readme: ftp://upload.kde.org/README
Upload: ftp://upload.kde.org/
  $ echo put myapp-0.1.tar.xz | ftp upload.kde.org
  $ echo put myapp-0.1.tar.xz.sig | ftp upload.kde.org

File a sysadmin ticket: https://go.kde.org/u/systickets

== Tagging ==

When you publish your tar you should also push the signed tag to the Git repo.

./tagme.rb 0.1

==  Announcing the Release ==

You can create a changelog using releaseme's logme script.

Once the sysadmins moved the tarball, you can announce the release. First, write a detailed blog post on a site that is aggregated on planet.kde.org. Then send a mail to kde-announce-apps@kde.org and your project's mailing list(s). The mail can be short and link to the longer announcement blog post.

You should include the full fingerprint to the GPG key used to sign the tar and tags in your announce e-mail.  (Don't put it on a wiki.)  Upload your key to openPGP key servers using  <code>gpg2 --send-keys <fingerprint></code>