Remove incubating, introduce experimental#1123
Conversation
felixbarny
left a comment
felixbarny
left a comment
There was a problem hiding this comment.
Let's deprecate incubating instead of removing entirely, to remain backwards compatibility.
| @Override | ||
| public Collection<String> getInstrumentationGroupNames() { | ||
| return Arrays.asList(HibernateSearchConstants.HIBERNATE_SEARCH_ORM_TYPE, "incubating"); | ||
| return Arrays.asList(HibernateSearchConstants.HIBERNATE_SEARCH_ORM_TYPE, "experimental"); |
There was a problem hiding this comment.
I'd add both incubating and experimental. Otherwise, it's a breaking change for people that have set disable_instrumentation=incubating,foo.
There was a problem hiding this comment.
Good point!
Not really related to this location- I will internally treat incubating as if it is an experimental tag
docs/intro.asciidoc
Outdated
| [float] | ||
| [[experimental]] | ||
| === Experimental features | ||
|
|
||
| Some agent features or <<supported-technologies-details,plugins>> are marked as `experimental`, which means: | ||
|
|
||
| * They are opt-in (disabled by default). | ||
| * There are no guarantees regarding changes in such features in future releases. | ||
| * In some cases they have special caveats or unknowns that come with them. | ||
| In such cases, the specific feature/plugin documentation should indicate that. | ||
|
|
||
| There are cases where we decide to release a feature as `experimental` to be on the safe side and only make it an official feature after we get some feedback about it. | ||
| Any such feedback will be highly appreciated, through a related GitHub issue or through the https://discuss.elastic.co/c/apm[APM discuss forum]. | ||
|
|
There was a problem hiding this comment.
I would remove this entire Experimental features section. I think it's repetitive. Here's why:
* They are opt-in (disabled by default).
* There are no guarantees regarding changes in such features in future releases.
The note below, included with all experimental features, already explains both of these points.
NOTE: This feature is currently experimental, which means it is disabled by default and it is not guaranteed to be backwards compatible in future releases.
The third bullet point explains that documentation will indicate if there are caveats or unknowns.
The only thing missing is the feedback point. If that's important, I say we just update the experimental tag to something like this:
NOTE: This feature is currently experimental, which means it is disabled by default and it is not guaranteed to be backwards compatible in future releases. Have feedback? Visit the https://discuss.elastic.co/c/apm[APM discuss forum].
There was a problem hiding this comment.
I agree. I added this because there are places that are not part of the configuration docs (like the tuning page or supported technologies page where we just say (experimental).
However, since in such places we DO refer to the enablement configuration, we can probably remove this section.
The only thing missing is the feedback point
I don't think I want to add that into these configuration docs multiple times. It's ok to leave out.
3 participants
Removing the
incubatingterm from our documentation if favour ofexperimentaland add some expectation setting regarding features labeled asexperimental.As part of that, the
incubatinginstrumentation group is deprecated, but this PR is still maintaining backwards compatibility fordisable_instrumentationconfigurations that use it.Checklist
Related issues
Closes #876