Sailfish Silica versioning

Applications QML
#1

Sailfish Silica does get updated regularly with new OS releases and as an enthusiastic user and developer, I am usually on the latest version. However, not all users are on the latest version and as a developer I would like to continue supporting these users as well.

It would be nice if Silica made use of the versioning system Qt/QML offers. This way as an developer I would be able to target older Silica versions with the QML engine and QtCreator giving a warning when using newly introduced components and properties for existing components. Right now, I would need depend on users on older versions submitting bug reports if something breaks in older Silica versions.

Sadly, as a student and the development of Sailfish applications being nothing more than a hobby, I do not have the resources to own multiple devices for testing. My Sailfish phone is my only and main device (besides a feature phone if the call part somehow would break).

As an example:

import QtQuick 5.6
import Sailfish.Silica 3.4 // Because of Sailfish 3.4

ApplicationWindow {
    background.color = "purple"; // Error: background.color is not a property of ApplicationWindow
}

If import Sailfish.Silica 4.0 was used, it wouldn’t give an error, since the property actually has been introduced with Sailfish 4.0.

7 Likes
New sailfishos.org - new developer pages?
#2

This would be great also from a maintenance point of view. Knowing which version a component was developed for helps with keeping track of outdated code, refactoring, and keeping things current.

I suggest not to base the version number on the Sailfish release number, though. It would be great if something like semantic versioning (semver.org) could be used, i.e. the major version should only change with major changes.

If versioning is implemented, it would be very important to have versioned documentation archives too. This would also help developers with keeping track of recent changes, which is important for writing good code.

4 Likes
#3

I was recently developing a few new features for Whisperfish, when I once again ran into this very issue: the version numbers in import Sailfish.Silica 1.0 and import Nemo.Notifications 1.0 have absolutely no meaning. Let me clarify.

Consider two QML elements for example: Notification (Nemo) and TextField (Silica). As of writing this, they both are at the version 1.0. As far as I know, the version hasn’t been changed.

import Nemo.Notifications 1.0 on Jolla Phone (SFOS 3.4) results in sound property being non-existent, whereas the same import in Sony Xperia 10 III (SFOS 4.4) there is such property. If there’s a new feature in a release, the API version should be increased accordingly. If it’s a breaking change, the major version should be increased. Qt seems to be very consistent with this behavior, I don’t really see why Silica and/or Nemo should neglect versioning. The same reasoning applies to Silica, TextField and its rightItem.

First: The import clause version does not correspond to the available features, but instead the underlying Sailfish OS version dictates them. The same import clause should always provide the same set of functionality, no matter the exact operating system version underneath.

Second: There is no easily available information about which QML features were featured in which SFOS releases. For example, by looking at the source code of Notifications QML plugin I can find the date Dec 16, 2020 which may or may not correspond to SFOS 4.0 release. The package version is updated however, but it has no context inside the QML file. I didn’t try to check TextField, it may be closed source component.

Third: This all is something that the software developer should not have to think about. The documentation should be clear about when the feature was first introduced. Qt documentation is again a good example; it is often separately written in the documentation: “This function was first introduced in Qt 5.6” or something similar. Change logs don’t help, although they hint about changes by having plugins.qmltypes mentioned here and there. Having to do guesswork instead of being able to rely on the documentation does not help in keeping the developers happy.

Fourth: Semver is awesome!

I came up with a few methods - in no particular order - to improve the current situation (some of which are already mentioned above):

  • Increase the version number with Sailfish OS version number
    • i.e. import Sailfish.Silica 4.5 for SFOS 4.5
    • dead simple for 3rd party developers
    • simple, but sub-optimal and non-standard
    • version number changes doesn’t correlate with changes
    • one documentation version for every SFOS release
  • Increase the version number whenever a new feature is about to be released in a Sailfish OS update
    • e.g. import Sailfish.Silica 1.1 for SFOS 4.5
    • minor version change indicates new feature
    • major version change indicates breaking change
    • would still need documentation of introduced SFOS version
    • one documentation version per feature release
  • Add the minimum Sailfish OS version of each property and method to documentation
    • most work
    • does now require changing working existing code
    • one documentation covers all SFOS releases
  • Add separate feature matrix document (table) per component
    • i.e. for Notification: | sound | âś— 3.4 | ? 4.0 | :heavy_check_mark: 4.4 |
    • would not require changes to existing pages
    • simply one new page per element
    • huge amount of information in one place
    • easy for the community to extend and add information
    • can be implemented by the community alone if all is rejected

It looks like the very first thing needed is the decision of what action to take.

The unfortunate part here is that while the community can help building the documentation, not all components are open source and thus are not accessible.

3 Likes
#4

Just chiming in to say +1 for semver and agreed that it would really make managing the divide easier. I’m only trying to cover 3.4/4.4 and failing pretty badly.

1 Like