New rule for Recommended Extensions: no @Unstable API usage

Development
#1

Hi devs,

Simon just made me realize that it would be a bad idea to recommend an extension that uses @Unstable APIs because if these APIs are modified, then the extension is broken and even if a new version is released then our users will be broken until they upgrade.

Thus I’d like to propose to add this rule (which is kind of obvious but I think it’s better to write it down) to the list of rules at https://extensions.xwiki.org/xwiki/bin/view/ExtensionCode/RecommendedExtensions/RecommendedDefinition/

WDYT?

Thanks

#2

Hi,

I’m coming back on this topic as I believe it was actually discussed more on the chat.
AFAIR we discussed with @tmortagne if the usage of @Unstable annotation in extension would make sense or not, because they don’t follow the same cycles as XS, so we don’t really know when they would be removed.

So IMO we should first clarify the usage of @Unstable in contrib extensions, before we go there. IMO for contrib extensions we should simply use semver for removing the annotations: when we bump to the next major version, then @Unstable should be removed.

#3

I’m not sure this rule is obvious. It is stated that a recommended extension might not work with the LTS version. However, the usual reason for not working with the LTS version is that the extension needs a new API, and this new API is normally unstable. Also, it can happen that a new API is added as @Unstable and the old API is moved to legacy before the new API becomes stable. In this case, I think an extension that targets a version that contains this state can only use the new, unstable API unless it explicitly depends on the legacy module.

#4

This is almost what UnstableAnnotationCheck checks already (see also Development Practices - XWiki) but it’s not 1 major but 2.

Example 1:

  • current version: 4.5 → currentVersionMajor = 4
  • @since 3.7 → sinceMajor = 3
  • Check: currentVersionMajor - 2 >= sinceMajor → 2 >= 3 → false => no breakage

Example 2:

  • current version: 5.0 → currentVersionMajor = 5
  • @since 3.7 → sinceMajor = 3
  • Check: currentVersionMajor - 2 >= sinceMajor → 3 >= 3 → ftruealse => breakage

The main problem I see is that Contrib extension don’t upgrade majors often (for XS it’s every year which means a max of 2 years before an API becomes stable, this is why it was convenient to use majors in the check). Similarly we need a max time for Contrib extensions. The hard part is that we don’t have a date specified in the @since annotation.

#5

Relying on version for @Unstable management does not really make sense for contrib extensions IMO. Many extensions (if not most) don’t increase the major version for years simply because there is no change big enough to justify it, and keeping an API marker with @Unstable for more than 5 years is totally pointless. The only reason why relying on the version works for XWiki Standard is because it has a very well-defined cycle or versions.

IMO, it does not make any sense to decide a rule for contrib extension in general, and it should be a case by case rule documented in each extension.