Adds tech preview macro, updates experimental (elastic#2340)

* adds tech preview macro, updates experimental

* updates usage section

* updates docs

* removes spaec

* and tidies

* Update resources/asciidoctor/lib/care_admonition/extension.rb

Co-authored-by: Greg Back <[email protected]>

* Update resources/asciidoctor/lib/care_admonition/extension.rb

Co-authored-by: Greg Back <[email protected]>

* feedback polish

* whitespace and styling nags

* fixes build

* fixes build

* Update test strings for tech preview admonition

* Make rubocop happy

* Make rubocop happier

Co-authored-by: Greg Back <[email protected]>
Co-authored-by: Greg Back <[email protected]>

Author: goodroot

README.asciidoc

@@ -1534,9 +1534,9 @@ deprecated::[0.90.4,Replace by `foo.baz`. See <<new-section>>]
 Text about old functionality...
 
 [[experimental]]
-== Beta, Dev, and Experimental
+== Beta, Dev, and Preview (experimental)
 
-APIs or parameters that are in beta, in development, or experimental can be
+APIs or parameters that are in beta, in development, or in technical preview (formerly experimental) can be
 marked as such, using markup similar to that used in <<changes>>.
 
 In the block format, you have the option of adding a related GitHub issue link.
@@ -1624,41 +1624,49 @@ This param is in development and may change in the future.
 
 === Using the `experimental` admonition
 
+Experimental language is deprecated.
+
+We decided on the much less raw sounding "technical preview".
+
+See below.
+
+=== Using the technical `preview` admonition
+
 [source,asciidoc]
 ----
 [[new-feature]]
-=== New experimental feature
+=== New feature in technical preview
 
-experimental::[]
+preview::[]
 
-experimental::[https://github.com/elastic/docs/issues/505]
+preview::[https://github.com/elastic/docs/issues/505]
 
-experimental::[{issue}505]
+preview::[{issue}505]
 
-experimental::["Custom text goes here."]
+preview::["Custom text goes here."]
 
-experimental::["Custom text goes here.",https://github.com/elastic/docs/issues/505]
+preview::["Custom text goes here.",https://github.com/elastic/docs/issues/505]
 
-experimental::["Custom text goes here.",{issue}505]
+preview::["Custom text goes here.",{issue}505]
 
 Text about new feature...
 
 [[old-feature]]
 === Established feature
 
 This feature has been around for a while, but we're adding
-a new experimental parameter:
+a new preview parameter:
 
 `established_param`::
 This param has been around for ages and won't change.
 
 `experimental_param`::
-experimental:[]
-This param is experimental and may change in the future.
+preview:[]
+This param is in technical preview and may change in the future.
 
 `experimental_param`::
-experimental:["Custom text goes here."]
-This param is experimental and may change in the future.
+preview:["Custom text goes here."]
+This param is in technical preview and may change in the future.
 ----
 
 [[images]]

integtest/spec/single_book_spec.rb

@@ -287,7 +287,10 @@
     page_context 'chapter.html' do
       it 'includes the experimental text' do
         expect(body).to include(
-          'This functionality is experimental and may be changed or removed'
+          'This functionality is in technical preview and may be changed or '\
+          'removed in a future release. Elastic will apply best effort to fix '\
+          'any issues, but features in technical preview are not subject to '\
+          'the support SLA of official GA features.'
         )
       end
     end

resources/asciidoctor/lib/care_admonition/extension.rb

@@ -3,16 +3,19 @@
 require 'asciidoctor/extensions'
 
 ##
-# Extensions for marking when something as `beta`, `dev`, or `experimental`.
+# Extensions for marking something as `beta`, `dev`, or technical `preview`.
 #
 # Usage
 #
 #   beta::[]
 #   dev::[]
-#   experimental::[]
+#   preview::[]
 #   Foo beta:[]
 #   Foo dev:[]
-#   Foo experimental:[]
+#   Foo preview:[]
+#
+# !! `experimental:[]` is supported as a deprecated alternative to `preview:[]`.
+# !! But please use `preview:[]` instead.
 #
 class CareAdmonition < Asciidoctor::Extensions::Group
   BETA_DEFAULT_TEXT = <<~TEXT.strip
@@ -21,15 +24,16 @@ class CareAdmonition < Asciidoctor::Extensions::Group
   DEV_DEFAULT_TEXT = <<~TEXT.strip
     This functionality is in development and may be changed or removed completely in a future release. These features are unsupported and not subject to the support SLA of official GA features.
   TEXT
-  EXPERIMENTAL_DEFAULT_TEXT = <<~TEXT.strip
-    This functionality is experimental and may be changed or removed completely in a future release. Elastic will take a best effort approach to fix any issues, but experimental features are not subject to the support SLA of official GA features.
+  PREVIEW_DEFAULT_TEXT = <<~TEXT.strip
+    This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
   TEXT
 
   def activate(registry)
     [
       [:beta, 'beta', BETA_DEFAULT_TEXT],
       [:dev, 'dev', DEV_DEFAULT_TEXT],
-      [:experimental, 'experimental', EXPERIMENTAL_DEFAULT_TEXT],
+      [:experimental, 'experimental', PREVIEW_DEFAULT_TEXT],
+      [:preview, 'preview', PREVIEW_DEFAULT_TEXT],
     ].each do |(name, role, default_text)|
       registry.block_macro ChangeAdmonitionBlock.new(role, default_text), name
       registry.inline_macro ChangeAdmonitionInline.new(role, default_text), name

resources/asciidoctor/spec/care_admonition_spec.rb

@@ -247,7 +247,17 @@ def expect_inline_admonition(text)
     let(:admon_class) { 'warning' }
     let(:default_text) do
       <<~TEXT.strip
-        This functionality is experimental and may be changed or removed completely in a future release. Elastic will take a best effort approach to fix any issues, but experimental features are not subject to the support SLA of official GA features.
+        This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
+      TEXT
+    end
+    include_examples 'care admonition'
+  end
+  context 'preview' do
+    let(:key) { 'preview' }
+    let(:admon_class) { 'warning' }
+    let(:default_text) do
+      <<~TEXT.strip
+        This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
       TEXT
     end
     include_examples 'care admonition'