Semantic versioning

Semantic versioning 🔗 is a way to versioning software 🔗. It is a very popular way to version software as it is not only easy to use, but also to understand. The version number schema is x.y.z where z is a patch, y a minor version, aka: a new feature and x is a major version. The major version is changed when: “MAJOR version when you make incompatible API changes” ¹.

For a project to be able to use semantic versioning, some rules must be followed. The more important ones regarding the handling of the major version (X.y.z) are:

• declare a public API
• changes are released under a new version (any one of x, y, z)
• any backward incompatible changes result in a major version increment

This means that any change in the public API that is backward incompatible - aka: a breaking change - triggers a new major version. This change can even be something small like changing a method parameter that will make apps stop working, or bigger changes like removing feature.s

Removed API

You might have come accross an announcement from UI5. Either on LinkedIn 🔗 or on SCN 🔗 that the sap.ui.webc library is removed in UI5 version 1.147.0. UI5 is using semver. Yet, removing an API is not triggering a major version increase. You might wonder how this is possible. An API is removed, and UI5 is still at version 1.y.z? Not 2.0.0? How can UI5 remove an API and still stay at version 1.y.z? Isn’t UI5 using semantic versioning? Is this even an error on their side?

The public API trick

UI5 is using a nice trick here. Semver is applied to the public API. The removed sap.ui.webc library however was never part of the public API. It was always marked as experimental. This did not made it part of the public API. Therefore, semver does not apply to changes to this library. Nice trick from UI5. Of course, if you were using the API in your app and were not aware of the experimental and the can-be-removed-any-time trick, you now have a problem. But: it’s your problem. You did not read carefully enough the API documentation.

You can argue that an API that is part of the released version and can be consumed by apps is public. From the API documentation, the visibility of the library is public. UI5 just declared that it is experimentals and therefore not part of the public API.

This is a nice trick for UI5 as it allows to solve their problem of having just one release. Things like this can be (better?) solved by using a separate experimental branch, or by using a version for experimental features 🔗. You can easily find people that would argue that a change like this must trigger a new major version. You can also find enough people that will defend the experimental hack. Either way: the library is removed and if you are affected: read carefully the documentation. The mixture of stable APIs and experimental APIs as UI5 is adding trial features they can remove at any given time means: only use what is not marked as experimental. For any app that is not intended to be short living, this should be already the norm.

Experimental and deprecated

The UI5 documentation provides a list of experimental 🔗 and deprecated 🔗 libraries. Go through the list carefully. Personally I find it too complicated to find information in there. For instance, sap.ui.webc is not listed in the experimental page. In the API documentation (see picture above) it is written: experimental as of 1.92.0. But this version is not listed.

Exactly the version where this library was added and marked as experimental is not listed in the experimental page. The library is listed in the deprecated page.

This is nice, but deprecated does not mean experimental. Deprecated in a public, release API in version 1.y.z still means: available until version 1 expires. WWhich might mean for UI5: somewhere in 2040+ and not 2026.