Add prerelease search parameter and deprecate experimental

[jsoriano]

Implements support for prerelease semver tags in the package registry, in the context of elastic/package-spec#225.

After this change, the package registry will return versions of packages in development only if prerelease=true or experimental=true parameters are included in the search requests. This shouldn't be breaking in current versions of Kibana because Kibana is currently always including experimental=true. A follow-up task will be created in Kibana to remove the uses of experimental, and add support for optionally enabling prerelease (elastic/kibana#122973).

Summarizing changes here:

• In-development versions of packages are not returned by default on search queries. A version is considered an in-development prerelease if it includes a prerelease tag, or if its major is 0.
• prerelease parameter is added to include versions of packages in development in search requests.
• experimental parameter is deprecated.
• For compatibility with current versions of Kibana, when experimental is set to true, prerelease is also set to true.
• Packages without a release tag and a stable version according to semver are considered GA for legacy API purposes, or beta if they are prerelease versions. Datastreams without a release tag have the same release level as its parent package.

[elasticmachine]

💚 Build Succeeded

the below badges are clickable and redirect to their specific view in the CI or DOCS

Expand to view the summary

Build stats

• Start Time: 2022-01-27T10:58:57.893+0000

• Duration: 5 min 17 sec

• Commit: b43b38a

Test stats 🧪

Test	Results
Failed	0
Passed	142
Skipped	0
Total	142

🤖 GitHub comments

To re-run your PR in the CI, just comment with:

• /test : Re-trigger the build.

[mtojek]

The PR looks good to me, but I left a few points which may lead to a longer discussion. Let me know what do you think.

[mtojek]

Out of curiosity, do you think we should perform an exercise and check how many packages are affected because of this change?

[jsoriano]

Packages with prerelease tags: 1, apm-server 8.0.0-rc1
Packages with major version 0: 48, they are all marked as beta or experimental, except a couple of them. We will have to think what to do about them. The couple of ga ones should be probably versioned as 1.x.

Btw, I have also found that kibana, logstash and microsoft packages are marked as experimental, but have 1.x versions, we will have to check this too.

I can delay the merge of this till we clarify the status of these packages.

[mtojek]

Implementation LGTM, let's just clarify affected packages.

[jsoriano]

Thinking about the (not few) packages with version 0.x, I am wondering if we would need three modes of operations for search:

• No prerelease package is returned (as with this PR with prerelease=false).
• All prerelease packages are returned (as with this PR with prerelease=true).
• A third mode, that for packages with stable versions only returns the stable versions (as with prerelease=false), but it also returns packages that only have prerelease versions. This mode would help to give visibility to integrations that are in development, as the ones with 0.x versions only, while keeping a stable channel for packages that have GA versions.

@mtojek @akshay-saraswat wdyt about this third mode?

[mtojek]

The third option might be hard to explain to users why some 0.x packages are considered GAs. It would be for keeping the rule as simple as possible 0.x = prerelease. We don't have many of them, so we can release the missing ones as 1.0. I'm happy to discuss it though!

BTW having packages marked as 0.2.0 or 0.6.0 and not maintaining them gives also a bad experience :) Users may consider them as unstable to use and discouraged to use the platform.

Maybe @ruflin can see some other benefits/drawbacks of this change that will help us take the best decision.

[jsoriano]

The third option might be hard to explain to users why some 0.x packages are considered GAs.

Well, they should still appear as non-GA somehow in the UIs, but yes, this mode would be a bit confusing, as prereleases would be available for some packages but not for others.

I would also prefer to keep rules simple for users, so they can clearly decide if they want prerelease packages or not in their deployments.

Probably the best is to keep pushing for GA versions of maintained packages, and keep this option simple.

[ruflin]

We had a similar discussion in the early days of the package registry. Initially only the GA packages were shown by default but we ended up with 3 packages so the change was made to show all the packages by default for the first iterations. Back then we had the discussion to have a toggle in the Fleet UI or a separate tab to show the prerelease too. It would be good to sync up on this with the Fleet team (@jen-huang @joshdover @mostlyjason ) before you roll out the change.

A pure technical thought: Every query param is a filter. That means by default ALL packages should be returned and from there the user can filter down. This would still allow Fleet to have prerelease=true by default and they could also change it at any time without requiring any change in the registry. This is basically your option 2 but internally it is treated like there is no filter.

[jsoriano]

It would be good to sync up on this with the Fleet team before you roll out the change.

Yep, I created elastic/kibana#122973 for the changes in Fleet.

A pure technical thought: Every query param is a filter. That means by default ALL packages should be returned and from there the user can filter down.

This is not exactly true with the current implementation. By default all non-experimental packages are returned, experimental=true is needed to include all packages (and all=true for all versions). I have followed this principle when implementing prerelease. By default the safest set of packages and versions are returned, and flags can be used to enable additional sets of packages.

Looking it from a pure data perspective, it makes more sense to return everything by default and filter down with parameters, but from the kind of operational data exposed here, I think it makes sense to have defaults that return more safe or relevant results, and use parameters to extend them in particular use cases.

[ruflin]

This is not exactly true with the current implementation.

I had exactly the same "challenge" when I implemented it the first time.

I can see both approaches work. The reason I think of the "filter down" part is there might become a point where the search index is served by Elasticsearch. In this scenario it would mean "adding" param to the request means under the hood the query is likely adjusted to remove a filter.

But as said before, both approaches will work, go with your preference.

[jsoriano]

Added changes to default release levels after this thread: elastic/package-spec#256 (comment)

[mtojek]

LGTM, I assume you will take the decision when to push this PR :)

[andrewkroh]

@jsoriano Can you please update the README to reflect these changes. It's missing prerelease param and should now show experimental as deprecated.

[jsoriano]

@jsoriano Can you please update the README to reflect these changes. It's missing prerelease param and should now show experimental as deprecated.

Good one, I'll do it, thanks!