Moving KDevelop to Release service coverage?

Wed Oct 27 09:12:10 BST 2021

On Thursday, 21 October 2021 18:57:59 CEST Friedrich W. H. Kossebau wrote:
> Am Donnerstag, 21. Oktober 2021, 09:37:51 CEST schrieb Milian Wolff:
> > On Mittwoch, 20. Oktober 2021 20:22:55 CEST Friedrich W. H. Kossebau 
wrote:
> > > Disadvantage:
> > > The awkward release-service-oriented branch names and version numbers. I
> > > would propose to use the 5.6.xyz (with xzy generated from the release
> > > service data) approach here, so the major and minor number is still
> > > under
> > > KDevelop control and to match whatever semantics it has, while the patch
> > > level is based on the Release service number.
> > 
> > We could also bump the version numbers to be in line with the other KDE
> > gear applciations, if that's needed. But I have to admit that I don't
> > really know what exactly you are talking about here - can you give a more
> > concrete example? We already use 5.6.xyz after all the way I see it?
> 
> Release service scripts hook into the sources to optionally provide version
> numbers by changing in the toplevel CMakeLists.txt file these lines if
> present:
> --- 8< ---
> set (RELEASE_SERVICE_VERSION_MAJOR "21")
> set (RELEASE_SERVICE_VERSION_MINOR "08")
> set (RELEASE_SERVICE_VERSION_MICRO "2")
> --- 8< ---
> 
> Applications can then use these variables to calculate their version number:
> e.g. by mapping it 1:1 (example Kate, KDE Gear 21.12.0 -> Kate 21.12.0) ---
> 8< ---
> set(RELEASE_SERVICE_VERSION "${RELEASE_SERVICE_VERSION_MAJOR}.$
> {RELEASE_SERVICE_VERSION_MINOR}.${RELEASE_SERVICE_VERSION_MICRO}")
> project(kate VERSION ${RELEASE_SERVICE_VERSION})
> --- 8< ---
> or using those numbers to calculate an ever-increasing patch-level number
> (example Konversation, KDE Gear 21.12.0 -> Konversation 1.8.21120):
> --- 8< ---
> set (RELEASE_SERVICE_COMPACT_VERSION "${RELEASE_SERVICE_VERSION_MAJOR}$
> {RELEASE_SERVICE_VERSION_MINOR}${RELEASE_SERVICE_VERSION_MICRO}")
> 
> # Bump KONVERSATION_BASE_VERSION once new features are added
> set(KONVERSATION_BASE_VERSION "1.8")
> set(KONVERSATION_VERSION "${KONVERSATION_BASE_VERSION}.$
> {RELEASE_SERVICE_COMPACT_VERSION}")
> --- 8< ---
> or do someething else or just ignore it and manually maintain an own scheme.
> 
> The branch names created by the Release service though will always be named
> "release/yy.mm", matching the year quarter cycle.
> 
> For other version numbers like SO version numbers Release service provides
> nothing, that is left to projects.
> 
> Back to KDevelop:
> Given KDevelop has public API for plugins, there needs to be some sense in
> the version number pointing to ABI/API compatibility. The yy.mm.p would be
> hard to use here at least with the capabilities of cmake, which relies on
> the semantic versioning scheme to compare version compatibility.
> And when we agree that KDevelop should continue promoting its plugin
> feature, 3rd-party projects need a sane way to check which API version they
> are building against.
> That is why I suggest to have KDevelop define the major & minor parts of the
> version itself as before, increasing the minor on API breakages and the
> major on big changes (like 5->6 for Qt6 port). While incrementing the patch
> level by deriving from the release service numbers.
> 
> So KDevelop's toplevel CMakeLists would do this to define the version:
> --- 8< ---
> set (RELEASE_SERVICE_VERSION_MAJOR "21")
> set (RELEASE_SERVICE_VERSION_MINOR "12")
> set (RELEASE_SERVICE_VERSION_MICRO "0")
> 
> set (RELEASE_SERVICE_COMPACT_VERSION "${RELEASE_SERVICE_VERSION_MAJOR}$
> {RELEASE_SERVICE_VERSION_MINOR}${RELEASE_SERVICE_VERSION_MICRO}")
> 
> project(KDevelop VERSION "5.7.${RELEASE_SERVICE_COMPACT_VERSION}")
> --- 8< ---
> That way things are automated and no one needs to stand by every release
> time. One catch though: given every quarter the master branch is branched
> into a new stable branch, if someone does an ABI breakage in the master
> branch they also need to remember to bump the minor version if not done
> since the last branching, as well as the KDEVELOP_SOVERSION and the
> KDEV_PLUGIN_VERSION. Can we expect us to manage to care for that?
> 
> Side comment: the latter two could be calculated from the major & minor
> version, and perhaps KDEV_PLUGIN_VERSION even be changed to be the
> KDEVELOP_SOVERSION? What is the offset for KDEV_PLUGIN_VERSION, and would
> there be any reason for bumping it differently from KDEVELOP_SOVERSION?
> 
> To help people who want map KDE Gear version to the KDevelop version they
> are using, the KDE Gear number could be given in brackets after the app
> version (e.g. PIM apps do that, KMail as "Version 5.18.2 (21.08.2)").
> 
> > > So, who would be in favour, who would not be in favour?
> > 
> > Let's go for it, I say!
> 
> Good, another +1 added to my collection :)

Hey, 

Friedrich asked me to comment here. Actually I'm not that much involved any 
more at the moment (busy with real-life). 

In general: +1 on most you've said. Thanks for the detailed analysis. 

I think the biggest problem is aligning the yy.mm versioning scheme when 
KDevelop is providing a public interface with some sense of API/ABI stability 
guarantees. As KDE's release-service-oriented approach does not align with the 
semantic versioning scheme at all. To be honest I've always disliked the way 
e.g. KDEPIM did it (by basically maintaining an internal and a public version 
in parallel). May confuse packagers, developers and users (reporting bugs) 
likewise.

What about just using the KDE yy.mm versioning as-is and keep using our 
KDEVELOP_SOVERSION var but which is now only bumped in case of public API/ABI 
breaks. KDEVELOP_SOVERSION could also be exported in CMake config files so 
users could use it to check against their requirements.

That means we could end up with a scenario like this:

- ...
- KDevelop release: 21.08, KDEVELOP_SOVERSION: 57
- KDevelop release: 21.12, KDEVELOP_SOVERSION: 57
- KDevelop release: 22.04, KDEVELOP_SOVERSION: 58 <- Some API break!
- KDevelop release: 22.08, KDEVELOP_SOVERSION: 58
- ...

Basically internally just think of KDEVELOP_SOVERSION representing:
 "${QT_MAJOR_VERSION}.${KDEVELOP_API_REVISION}"

If plugin authors depend on an API feature from "58", just let them depend on 
KDevelop 21.12. Maybe above relation from yy.mm to SOVERSION could be 
persisted on the web page as well. Shouldn't be much work.

If we would want to align with semantic versioning rules a bit more [1], we 
could even mandate to not allow API/ABI breakage in minor releases => that 
means API/ABI is stable for e.g. the 22.mm lifetime. IOW you're only allowed 
to break API/ABI at the start of a year. I think not /too/ bad given that 
KDevelop has had relatively stable API/ABI. But no hard feelings if you say 
this is non-sense.

Anyhow, I have no time to put much more thought on this. I'm trusting 
Friedrich to do the right thing :tm: here. 

I agree that being part of a properly planned release cycle is good for us, 
for other drivy-by developers providing patches and packagers likewise. Just 
for planning and expectation management.

Hope that helps,
Kevin

> Cheers
> Friedrich

[1] https://semver.org/ -- Particularly the rule: "Given a version number 
MAJOR.MINOR.PATCH, increment the MAJOR version when you make incompatible API 
changes".

-- 
Kevin Funk | kfunk at kde.org | http://kfunk.org
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 195 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/kdevelop-devel/attachments/20211027/9106e9f8/attachment.sig>