ReleasingSoftware: Difference between revisions

From KDE Community Wiki
(Fixed git sub-command for branch creation)
(Move KDE Review to developer documentation)
 
(46 intermediate revisions by 17 users not shown)
Line 1: Line 1:
This page documents the steps to release software packages developed by the KDE community. This guide applies to all software which is '''not''' part of a bigger bundle like Frameworks, Plasma and "KDE Applications", which have specific release cycles and release managers.
This page documents the steps to release software packages developed by the KDE community. 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.


== Sanity Checklist ==
== Sanity Checklist ==
Before releasing a beta or stable release of a KDE project you should have completed (or at least be going through) [https://develop.kde.org/docs/getting-started/add-project/#kde-review KDE Review].


Stuff your project should have before beta or final release:
Rollout of Gitlab CI: https://mail.kde.org/pipermail/kde-devel/2021-October/000735.html , Gitlab CI Dashboards and retirement of build.kde.org: https://mail.kde.org/pipermail/kde-devel/2022-September/001270.html, Debugging KDE CI runners: https://mail.kde.org/pipermail/kde-devel/2022-October/001401.html
* 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]
[https://phabricator.kde.org/maniphest/task/edit/form/2/ Sysadmin request] form for bugs.kde.org products.
* 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]
For KDE neon ask on [https://matrix.to/#/#kde-neon:kde.org KDE neon room]
* 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
Example CI job at e.g. [https://invent.kde.org/plasma/plasma-disks/-/blob/master/.gitlab-ci.yml plasma-disks CI] and [https://invent.kde.org/plasma/plasma-disks/-/jobs plasma-disks reuse jobs]
* Documentation appropriate to the project: API documentation, user documentation (including docbook or other format documented by the Documentation team)


== Branching ==
== 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.
Before you create a release, if you plan to maintain a stable branch and release bugfix version from it, 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">
<source lang="bash">
Line 23: Line 23:
You can also branch after making a tar using releaseme's branchme.rb script
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.
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. Make sure you get a confirmation that your request has been handled.
 
For people using kdesrc-build and [https://build.kde.org/ KDE's CI build.kde.org], once you have created and pushed a new stable branch you need to update also [https://invent.kde.org/sysadmin/repo-metadata repo-metadata]:
* Change the branch name for "stable-kf5-qt5" in the the file "logical-module-structure"
* Update dependencies listed in the file "dependency-data-stable-kf5-qt5" if needed (wildcard rules might keep you covered, explicit listing done only for non-basic needs)
 
When your product is covered on build.kde.org, after that you also need to trigger some jobs, so build.kde.org can catch up. For that follow this [[Infrastructure/Continuous_Integration_System#Updating_builds_on_switching_the_.22stable.22_branch|workflow]].
 
When your product is covered on [https://binary-factory.kde.org/ KDE's package/installer generator binary-factory.kde.org], after you created and pushed a new stable branch you will also need to update the configuration of [https://invent.kde.org/packaging/craft-blueprints-kde/ craft-blueprints-kde] and possibly [https://invent.kde.org/sysadmin/binary-factory-tooling.git/ binary-factory-tooling]. The actual changes depend on the project and should be documented with them.


== Freezing ==
== Freezing ==
Line 29: Line 37:
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.
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 <[email protected]> . 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.
Before a release, you'll need to give translators a notification about the upcoming new version. If you created a stable branch, 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 <[email protected]> . At this point, do not do any changes to translated strings, i.e. consider your branch (or master, if you didn't create a separate 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.
Note: Other feature branches will always be unfrozen, and any kind of strings or features can be changed/added. If you created a separate release branch, also the master branch is not frozen.


== Versioning in source code and libraries ==
== Versioning in source code and libraries ==
Line 77: Line 85:


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.
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.
== Versioning in AppStream files ==
The AppStream appdata.xml and metainfo.xml file should include the release version and date, this info will be shown in software centers (Discover, Gnome Software) and repositories such as Flathub.
You can use the script in https://invent.kde.org/sysadmin/appstream-metainfo-release-update to add and update the release info.


== Creating a Tarball ==
== Creating a Tarball ==


The kde:releaseme scripts help with that.
The [https://invent.kde.org/sdk/releaseme releaseme] scripts help with that.


First check you have a working gpg2 install and a key set up which can do the digital signature:
First check you have a working gpg2 install and a key set up which can do the digital signature:
Line 95: Line 109:
This will create myapp-0.1.tar.xz and its digital signature myapp-0.1.tar.xz.sig
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]
--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://invent.kde.org/sysadmin/repo-metadata/ repo_metadata]


== Uploading the Tar ==
== Uploading the Tar ==


Read readme: ftp://upload.kde.org/README
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
Upload to ftp://upload.kde.org/, for example via ''curl''
  curl -T "myapp-0.1.tar.xz{,.sig}" ftp://upload.kde.org/incoming/
 
or via the traditional ''ftp'' command line program:
  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: https://go.kde.org/u/systickets


== Tagging ==
== Tagging ==
Line 112: Line 130:
./tagme.rb --version 0.1
./tagme.rb --version 0.1
</source>
</source>
This uses git running gpg to tag, you may need to set with
This uses git running gpg to tag, you may need to set with (see https://help.github.com/articles/telling-git-about-your-gpg-key/)
<source lang="bash">
<source lang="bash">
  git config --global user.signingkey
  git config --global user.signingkey
Line 128: Line 146:
==  Announcing the Release ==
==  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 send a mail to [email protected] 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.


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-[email protected] 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>


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>
Ideally you also want to sign your email with the key in question to proof that you have control over the key.

Latest revision as of 13:00, 21 December 2023

This page documents the steps to release software packages developed by the KDE community. 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.

Sanity Checklist

Before releasing a beta or stable release of a KDE project you should have completed (or at least be going through) KDE Review.

Rollout of Gitlab CI: https://mail.kde.org/pipermail/kde-devel/2021-October/000735.html , Gitlab CI Dashboards and retirement of build.kde.org: https://mail.kde.org/pipermail/kde-devel/2022-September/001270.html, Debugging KDE CI runners: https://mail.kde.org/pipermail/kde-devel/2022-October/001401.html

Sysadmin request form for bugs.kde.org products.

For KDE neon ask on KDE neon room

Example CI job at e.g. plasma-disks CI and plasma-disks reuse jobs

Branching

Before you create a release, if you plan to maintain a stable branch and release bugfix version from it, 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.

git checkout -b 1.2
git push --set-upstream origin 1.2

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 kde-i18n-doc to ask for translations to also be branched and repo-metadata to be updated. Make sure you get a confirmation that your request has been handled.

For people using kdesrc-build and KDE's CI build.kde.org, once you have created and pushed a new stable branch you need to update also repo-metadata:

  • Change the branch name for "stable-kf5-qt5" in the the file "logical-module-structure"
  • Update dependencies listed in the file "dependency-data-stable-kf5-qt5" if needed (wildcard rules might keep you covered, explicit listing done only for non-basic needs)

When your product is covered on build.kde.org, after that you also need to trigger some jobs, so build.kde.org can catch up. For that follow this workflow.

When your product is covered on KDE's package/installer generator binary-factory.kde.org, after you created and pushed a new stable branch you will also need to update the configuration of craft-blueprints-kde and possibly binary-factory-tooling. The actual changes depend on the project and should be documented with them.

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. If you created a stable branch, 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 <[email protected]> . At this point, do not do any changes to translated strings, i.e. consider your branch (or master, if you didn't create a separate branch) to be "string-frozen". If you do need a string changed, ask the translators for a string-freeze exception.

Note: Other feature branches will always be unfrozen, and any kind of strings or features can be changed/added. If you created a separate release branch, also the master branch is not frozen.

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:

cmake_policy(SET CMP0048 NEW)
project(kgraphviewer VERSION "2.4.0")

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

#usage somewhere in cmake for a library:
set_target_properties(kgraphviewerlib PROPERTIES VERSION ${PROJECT_VERSION} SOVERSION ${KGRAPHVIEWER_SOVERSION} OUTPUT_NAME kgraphviewer )

The config-kgraphviewer.h looks like this:

/* 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

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.

Versioning in AppStream files

The AppStream appdata.xml and metainfo.xml file should include the release version and date, this info will be shown in software centers (Discover, Gnome Software) and repositories such as Flathub.

You can use the script in https://invent.kde.org/sysadmin/appstream-metainfo-release-update to add and update the release info.

Creating a Tarball

The releaseme scripts help with that.

First check you have a working gpg2 install and a key set up which can do the digital signature:

echo test > test.text; gpg2 --armor --detach-sign -o test.text.sig test.text

If that works create the tar:

./tarme.rb --version 0.1 --origin stable myapp

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 repo_metadata

Uploading the Tar

Read readme: ftp://upload.kde.org/README

Upload to ftp://upload.kde.org/, for example via curl

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

or via the traditional ftp command line program:

 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: 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 --version 0.1

This uses git running gpg to tag, you may need to set with (see https://help.github.com/articles/telling-git-about-your-gpg-key/)

 git config --global user.signingkey

test with

 git init; echo asdf > asdf; git add asdf; git commit -a -m 'commit'; git tag -s -m 'Tagging #{options[:version]}' v123 HEAD

Updating bugzilla

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 for the tarballs (see #Uploading_the_Tar)

Announcing the Release

Once the sysadmins moved the tarball, you can announce the release. First send a mail to [email protected] 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.

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 gpg2 --send-keys <fingerprint>

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