Define recommendations for tagging non-GA features in GA packages

[jsoriano]

There have been some discussions about how to tag non-GA features in GA packages. This is relevant to make clear to the user what is the expected supportability level for the features they use.

Usually the approach in Elastic products has been to tag non-GA features, usually as beta or experimental, in the documentation.

The approach in Beats has been basically the following:

• For modules and metric/filesets, use the release tags in the fields.yml files. This is translated to documentation automatically.
• For other features, a warning is manually added in the documentation.
• For features that have Go code, usually a warning is logged too when the feature is used in runtime.

In packages:

• release tags (or versioning) can be used for packages and datastreams. For the case of packages, they are translated to UI elements in Kibana.
• For other features there is no consensus. If done, it is done in the documentation.

In packages there is the special case of the policy templates, that are data streams that appear as first-level integration tiles in the integrations page in Kibana. It'd be nice if they can show their release level already there.

Packages as a whole are out of this discussion, it has been decided to use SemVer, see #225.

Proposal

Completely open for discussion, but to frame the conversation I think that we can approach it from three angles:

• Option 1: Use documentation only.
  • Pros: Same thing for all features. No special code needed to handle it.
  • Cons: Users need to read the documentation to know if what they use is GA. Not possible or difficult to consume by tools or Kibana.
• Option 2: Use specific tags for specific kinds of features.
  • Pros: Can be consumed by tools or Kibana. Already done for data streams.
  • Cons: Specific implementations needed for each kind of feature. Features not covered by these tags would still need to be documented somewhere.
• Option 3: Add a generic list of non-GA features to a package manifest (each item in list an object with feature description, feature kind, release level and notes):
  • Pros: Same thing for all features. Can be consumed by tools or Kibana.
  • Cons: Additional code and specs needed for this.

[ruflin]

integration tiles, that are data streams that appear as first-level elements in the integrations page

Is this the case? Aren't these policy_templates? https://github.com/elastic/package-storage/blob/production/packages/aws/1.9.0/manifest.yml#L78

I would like use to take a mixed approach. For the most common "items" that can be in beta, lets have a shared approach based on which the UI can show the right properties. And then for the edge case / special cases, lets use docs. These docs can also be in the UI directly.

One potential approach I could see us taking is that we approach it at first from a UI perspective to see where the UI would potentially have to show "beta" labels or similar and then figure out this translates into the spec.

[jsoriano]

Is this the case? Aren't these policy_templates? https://github.com/elastic/package-storage/blob/production/packages/aws/1.9.0/manifest.yml#L78

👍 Fixed description.

I would like use to take a mixed approach. For the most common "items" that can be in beta, lets have a shared approach based on which the UI can show the right properties. And then for the edge case / special cases, lets use docs. These docs can also be in the UI directly.

This would be like option 2, that is something like what we have now. We would need to introduce a release tag in policy_templates (as I think you proposed in an internal thread) if we want integration tiles to have their own release level.