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.

#6

I still think we can have a general rule, which is similar as for XS. For XS the rule is that an unstable api cannot stay instable for more than 2 years. We could have the same for extensions or if we consider that 2 years is too long for an extension, reduce it to 1 year. I’d much prefer this than saying that it’s up to the extension as we all know that if we do this, it’ll never happen and young apis will not be well managed.

The only challenge is in finding how to implement this rule based on time instead of on version.

Proposal:

  • Allow specifying a date inside the @since javadoc tag, using a determined syntax. For example: @since 1.1 (2023-06-19). Our SinceFormatCheck and UnstableAnnotationCheck classes would be modified to support validating and parsing it.
  • Have a Maven pom property to force using a date inside the @since javadoc tag and fail the build if not used. We would then update the contrib parent poms to enable this property.

WDYT?

Thanks

#7

I’m not a big fan of putting a date in the @since.

What about doing it the other way around and introduce a way to be more explicit about how long something is planned to be unstable like @Unstable(until = "2024-06-19"). If you don’t indicate anything, then the rule is the XWiki Standard style version cycle based rule.

#8

My problem with the dev specifying until is that it’s not up to the dev to decide for each api, that would be not very useful (since the dev can put whatever he/she wants), nor consistent IMO. I much prefer a common rule of say: young api cannot stay more than 1 year for contrib extensions for example.

#9

I see one cons to that one. If you decide to change the “unstability” period, you need to change all the places. Whereas, if you set the date of introduction of the feature, you just have to change the period config.

#10

I’m not sure I’m following here. The original proposal in the first post and the title is to disallow the usage of unstable APIs in extensions, i.e., the usage of APIs that are marked with @Unstable in XS in an extension. I don’t understand why this topic is suddenly about how to mark and how long to keep @Unstable-annotations in extensions.

1 Like
#11

I’ve the feeling that we’re not discussing the original question, because I hijacked the topic when talking about using @Unstable in extension here:

So there’s currently two things discussed in this topic:

  1. the original question was about allowing or not extensions to use APIs that are unstable:

I think it’s actually what Michael was answering while all the others are talking about the second question following my post which is

  1. if extensions should use and how the @Unstable annotation in their API

Sorry for creating a mess with my answer back then…