elastic / elastic/package-spec
Define recommendations for tagging non-GA features in GA packages
- Dominant language
- Go
- Stars
- 20
- Forks
- 93
- Avg merge
- 15h 10m
- Merged PRs (30d)
- 12
Description
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](https://github.com/elastic/package-spec/issues/225)) 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 https://github.com/elastic/package-spec/issues/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.
Contributor guide
Assessment
This issue has not been assessed yet.