From d362f669122474f18ae68fba6efd726db4025340 Mon Sep 17 00:00:00 2001 From: Kellen <9484709+goodroot@users.noreply.github.com> Date: Thu, 6 Jan 2022 12:40:02 -0800 Subject: [PATCH 01/14] adds tech preview macro, updates experimental --- integtest/spec/single_book_spec.rb | 2 +- .../asciidoctor/lib/care_admonition/extension.rb | 7 ++++++- resources/asciidoctor/spec/care_admonition_spec.rb | 12 +++++++++++- 3 files changed, 18 insertions(+), 3 deletions(-) diff --git a/integtest/spec/single_book_spec.rb b/integtest/spec/single_book_spec.rb index efa271a75527a..3460ad797213f 100644 --- a/integtest/spec/single_book_spec.rb +++ b/integtest/spec/single_book_spec.rb @@ -287,7 +287,7 @@ 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 completely in a future release. Elastic will take a best effort approach to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.' ) end end diff --git a/resources/asciidoctor/lib/care_admonition/extension.rb b/resources/asciidoctor/lib/care_admonition/extension.rb index 7a8dcb643e420..46e933dd2a9c3 100644 --- a/resources/asciidoctor/lib/care_admonition/extension.rb +++ b/resources/asciidoctor/lib/care_admonition/extension.rb @@ -22,7 +22,10 @@ class CareAdmonition < Asciidoctor::Extensions::Group 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. + This functionality is in technical preview and may be changed or removed completely in a future release. Elastic will take a best effort approach to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. + TEXT + PREVIEW_DEFAULT_TEXT = <<~TEXT.strip + This functionality is in technical preview and may be changed or removed completely in a future release. Elastic will take a best effort approach to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. TEXT def activate(registry) @@ -30,6 +33,8 @@ def activate(registry) [:beta, 'beta', BETA_DEFAULT_TEXT], [:dev, 'dev', DEV_DEFAULT_TEXT], [:experimental, 'experimental', EXPERIMENTAL_DEFAULT_TEXT], + [:preview, 'experimental', 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 diff --git a/resources/asciidoctor/spec/care_admonition_spec.rb b/resources/asciidoctor/spec/care_admonition_spec.rb index 3f49ec44b0129..ec6899e6a92c7 100644 --- a/resources/asciidoctor/spec/care_admonition_spec.rb +++ b/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 completely in a future release. Elastic will take a best effort approach 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 completely in a future release. Elastic will take a best effort approach 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' From 12203b43b1768bbf6c61df48825329aeb87c78fa Mon Sep 17 00:00:00 2001 From: Kellen <9484709+goodroot@users.noreply.github.com> Date: Thu, 6 Jan 2022 12:47:03 -0800 Subject: [PATCH 02/14] updates usage section --- resources/asciidoctor/lib/care_admonition/extension.rb | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/resources/asciidoctor/lib/care_admonition/extension.rb b/resources/asciidoctor/lib/care_admonition/extension.rb index 46e933dd2a9c3..e333b6bfb8945 100644 --- a/resources/asciidoctor/lib/care_admonition/extension.rb +++ b/resources/asciidoctor/lib/care_admonition/extension.rb @@ -3,17 +3,20 @@ require 'asciidoctor/extensions' ## -# Extensions for marking when something as `beta`, `dev`, or `experimental`. +# Extensions for marking when something as `beta`, `dev`, or technical `preview`. # # Usage # # beta::[] # dev::[] -# experimental::[] +# preview::[] # Foo beta:[] # Foo dev:[] -# Foo experimental:[] +# +# !! experimental is deprecated, use preview # + + class CareAdmonition < Asciidoctor::Extensions::Group BETA_DEFAULT_TEXT = <<~TEXT.strip This functionality is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features. From dfa28ab7f47cd4f8f593ff1a4c2ccb4908f64898 Mon Sep 17 00:00:00 2001 From: Kellen <9484709+goodroot@users.noreply.github.com> Date: Thu, 6 Jan 2022 12:48:26 -0800 Subject: [PATCH 03/14] updates docs --- README.asciidoc | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/README.asciidoc b/README.asciidoc index ca1202474b8f0..977a55b851059 100644 --- a/README.asciidoc +++ b/README.asciidoc @@ -1629,17 +1629,30 @@ This param is in development and may change in the future. [[new-feature]] === New experimental feature -experimental::[] +Experimental language is deprecated. -experimental::[https://github.com/elastic/docs/issues/505] +We decided on the much less raw sounding "technical preview". -experimental::[{issue}505] +See below. -experimental::["Custom text goes here."] +=== Using the technical `preview` admonition -experimental::["Custom text goes here.",https://github.com/elastic/docs/issues/505] +[source,asciidoc] +---- +[[new-feature]] +=== New feature in technical preview + +preview::[] + +preview::[https://github.com/elastic/docs/issues/505] + +preview::[{issue}505] + +preview::["Custom text goes here."] + +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... From c8245ad23dcf017ea1c14a62712cd4ea502ef07e Mon Sep 17 00:00:00 2001 From: Kellen <9484709+goodroot@users.noreply.github.com> Date: Thu, 6 Jan 2022 12:49:18 -0800 Subject: [PATCH 04/14] removes spaec --- resources/asciidoctor/lib/care_admonition/extension.rb | 1 - 1 file changed, 1 deletion(-) diff --git a/resources/asciidoctor/lib/care_admonition/extension.rb b/resources/asciidoctor/lib/care_admonition/extension.rb index e333b6bfb8945..808305639ec29 100644 --- a/resources/asciidoctor/lib/care_admonition/extension.rb +++ b/resources/asciidoctor/lib/care_admonition/extension.rb @@ -37,7 +37,6 @@ def activate(registry) [:dev, 'dev', DEV_DEFAULT_TEXT], [:experimental, 'experimental', EXPERIMENTAL_DEFAULT_TEXT], [:preview, 'experimental', 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 From b2e43b1cd22cc06bb056ef9769303d639e79fcec Mon Sep 17 00:00:00 2001 From: Kellen <9484709+goodroot@users.noreply.github.com> Date: Thu, 6 Jan 2022 12:50:04 -0800 Subject: [PATCH 05/14] and tidies --- resources/asciidoctor/lib/care_admonition/extension.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/resources/asciidoctor/lib/care_admonition/extension.rb b/resources/asciidoctor/lib/care_admonition/extension.rb index 808305639ec29..c30588c7b98ea 100644 --- a/resources/asciidoctor/lib/care_admonition/extension.rb +++ b/resources/asciidoctor/lib/care_admonition/extension.rb @@ -36,7 +36,7 @@ def activate(registry) [:beta, 'beta', BETA_DEFAULT_TEXT], [:dev, 'dev', DEV_DEFAULT_TEXT], [:experimental, 'experimental', EXPERIMENTAL_DEFAULT_TEXT], - [:preview, '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 From 086289907f071d524da315d0e94ca768b4d8bc42 Mon Sep 17 00:00:00 2001 From: Kellen <9484709+goodroot@users.noreply.github.com> Date: Thu, 6 Jan 2022 15:03:50 -0800 Subject: [PATCH 06/14] Update resources/asciidoctor/lib/care_admonition/extension.rb Co-authored-by: Greg Back <1045796+gtback@users.noreply.github.com> --- resources/asciidoctor/lib/care_admonition/extension.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/resources/asciidoctor/lib/care_admonition/extension.rb b/resources/asciidoctor/lib/care_admonition/extension.rb index c30588c7b98ea..8fb0175dff760 100644 --- a/resources/asciidoctor/lib/care_admonition/extension.rb +++ b/resources/asciidoctor/lib/care_admonition/extension.rb @@ -35,7 +35,7 @@ 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 From 0f0750ba5d8ef81d92f6b73fc513d013f2115a30 Mon Sep 17 00:00:00 2001 From: Kellen <9484709+goodroot@users.noreply.github.com> Date: Thu, 6 Jan 2022 15:04:10 -0800 Subject: [PATCH 07/14] Update resources/asciidoctor/lib/care_admonition/extension.rb Co-authored-by: Greg Back <1045796+gtback@users.noreply.github.com> --- resources/asciidoctor/lib/care_admonition/extension.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/resources/asciidoctor/lib/care_admonition/extension.rb b/resources/asciidoctor/lib/care_admonition/extension.rb index 8fb0175dff760..0d7e52a6ef6ce 100644 --- a/resources/asciidoctor/lib/care_admonition/extension.rb +++ b/resources/asciidoctor/lib/care_admonition/extension.rb @@ -13,7 +13,7 @@ # Foo beta:[] # Foo dev:[] # -# !! experimental is deprecated, use preview +# !! `experimental:[]` is supported as deprecated alternative to `preview:[]`. But please use `preview:[]` instead. # From 6ab9ae361f1edde8fd1bafeadf3b3fd4436890f1 Mon Sep 17 00:00:00 2001 From: Kellen <9484709+goodroot@users.noreply.github.com> Date: Thu, 6 Jan 2022 15:09:57 -0800 Subject: [PATCH 08/14] feedback polish --- README.asciidoc | 19 +++++++------------ .../lib/care_admonition/extension.rb | 7 +++---- 2 files changed, 10 insertions(+), 16 deletions(-) diff --git a/README.asciidoc b/README.asciidoc index 977a55b851059..cf1e046df892d 100644 --- a/README.asciidoc +++ b/README.asciidoc @@ -1534,9 +1534,9 @@ deprecated::[0.90.4,Replace by `foo.baz`. See <>] 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 <>. In the block format, you have the option of adding a related GitHub issue link. @@ -1624,11 +1624,6 @@ This param is in development and may change in the future. === Using the `experimental` admonition -[source,asciidoc] ----- -[[new-feature]] -=== New experimental feature - Experimental language is deprecated. We decided on the much less raw sounding "technical preview". @@ -1660,18 +1655,18 @@ Text about new 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]] diff --git a/resources/asciidoctor/lib/care_admonition/extension.rb b/resources/asciidoctor/lib/care_admonition/extension.rb index 0d7e52a6ef6ce..d77a81434c62c 100644 --- a/resources/asciidoctor/lib/care_admonition/extension.rb +++ b/resources/asciidoctor/lib/care_admonition/extension.rb @@ -12,8 +12,10 @@ # preview::[] # Foo beta:[] # Foo dev:[] +# Foo preview:[] # -# !! `experimental:[]` is supported as deprecated alternative to `preview:[]`. But please use `preview:[]` instead. +# !! `experimental:[]` is supported as deprecated alternative to `preview:[]`. +# !! But please use `preview:[]` instead. # @@ -24,9 +26,6 @@ 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 in technical preview and may be changed or removed completely in a future release. Elastic will take a best effort approach to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. - TEXT PREVIEW_DEFAULT_TEXT = <<~TEXT.strip This functionality is in technical preview and may be changed or removed completely in a future release. Elastic will take a best effort approach to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. TEXT From 6846cafc5157f6e1e0c24b2197ccb7cc2279d6ed Mon Sep 17 00:00:00 2001 From: Kellen <9484709+goodroot@users.noreply.github.com> Date: Thu, 6 Jan 2022 15:23:05 -0800 Subject: [PATCH 09/14] whitespace and styling nags --- resources/asciidoctor/lib/care_admonition/extension.rb | 2 -- 1 file changed, 2 deletions(-) diff --git a/resources/asciidoctor/lib/care_admonition/extension.rb b/resources/asciidoctor/lib/care_admonition/extension.rb index d77a81434c62c..69ab3f239e891 100644 --- a/resources/asciidoctor/lib/care_admonition/extension.rb +++ b/resources/asciidoctor/lib/care_admonition/extension.rb @@ -1,5 +1,4 @@ # frozen_string_literal: true - require 'asciidoctor/extensions' ## @@ -18,7 +17,6 @@ # !! But please use `preview:[]` instead. # - class CareAdmonition < Asciidoctor::Extensions::Group BETA_DEFAULT_TEXT = <<~TEXT.strip This functionality is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features. From f7fa29b11b55ca5dec2096af470c04cff7607b2d Mon Sep 17 00:00:00 2001 From: Kellen <9484709+goodroot@users.noreply.github.com> Date: Mon, 10 Jan 2022 09:49:22 -0800 Subject: [PATCH 10/14] fixes build --- resources/asciidoctor/lib/care_admonition/extension.rb | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/resources/asciidoctor/lib/care_admonition/extension.rb b/resources/asciidoctor/lib/care_admonition/extension.rb index 69ab3f239e891..cf39d55ecb4f2 100644 --- a/resources/asciidoctor/lib/care_admonition/extension.rb +++ b/resources/asciidoctor/lib/care_admonition/extension.rb @@ -1,4 +1,5 @@ # frozen_string_literal: true + require 'asciidoctor/extensions' ## @@ -25,7 +26,7 @@ class CareAdmonition < Asciidoctor::Extensions::Group 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 PREVIEW_DEFAULT_TEXT = <<~TEXT.strip - This functionality is in technical preview and may be changed or removed completely in a future release. Elastic will take a best effort approach to fix any issues, but features in technical preview 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 def activate(registry) From 0fad371eabbd9fc65e7a0dd8c5ad67cb2de23537 Mon Sep 17 00:00:00 2001 From: Kellen <9484709+goodroot@users.noreply.github.com> Date: Mon, 10 Jan 2022 09:57:13 -0800 Subject: [PATCH 11/14] fixes build --- resources/asciidoctor/lib/care_admonition/extension.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/resources/asciidoctor/lib/care_admonition/extension.rb b/resources/asciidoctor/lib/care_admonition/extension.rb index cf39d55ecb4f2..83f0910343de9 100644 --- a/resources/asciidoctor/lib/care_admonition/extension.rb +++ b/resources/asciidoctor/lib/care_admonition/extension.rb @@ -14,7 +14,7 @@ # Foo dev:[] # Foo preview:[] # -# !! `experimental:[]` is supported as deprecated alternative to `preview:[]`. +# !! `experimental:[]` is supported as a deprecated alternative to `preview:[]`. # !! But please use `preview:[]` instead. # From 74f2213a8e1938a6b8fbc07d25c5f3af22c83bfc Mon Sep 17 00:00:00 2001 From: Greg Back Date: Thu, 20 Jan 2022 13:51:43 -0500 Subject: [PATCH 12/14] Update test strings for tech preview admonition --- integtest/spec/single_book_spec.rb | 2 +- resources/asciidoctor/spec/care_admonition_spec.rb | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/integtest/spec/single_book_spec.rb b/integtest/spec/single_book_spec.rb index 3460ad797213f..0ac7a9329bd40 100644 --- a/integtest/spec/single_book_spec.rb +++ b/integtest/spec/single_book_spec.rb @@ -287,7 +287,7 @@ page_context 'chapter.html' do it 'includes the experimental text' do expect(body).to include( - 'This functionality is in technical preview and may be changed or removed completely in a future release. Elastic will take a best effort approach to fix any issues, but features in technical preview 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.' ) end end diff --git a/resources/asciidoctor/spec/care_admonition_spec.rb b/resources/asciidoctor/spec/care_admonition_spec.rb index ec6899e6a92c7..0178cd54a41b3 100644 --- a/resources/asciidoctor/spec/care_admonition_spec.rb +++ b/resources/asciidoctor/spec/care_admonition_spec.rb @@ -247,7 +247,7 @@ def expect_inline_admonition(text) let(:admon_class) { 'warning' } let(:default_text) do <<~TEXT.strip - This functionality is in technical preview and may be changed or removed completely in a future release. Elastic will take a best effort approach to fix any issues, but features in technical preview 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' @@ -257,7 +257,7 @@ def expect_inline_admonition(text) let(:admon_class) { 'warning' } let(:default_text) do <<~TEXT.strip - This functionality is in technical preview and may be changed or removed completely in a future release. Elastic will take a best effort approach to fix any issues, but features in technical preview 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' From 02971371405d2e390e996eadbd617068573846dd Mon Sep 17 00:00:00 2001 From: Greg Back Date: Thu, 20 Jan 2022 14:03:53 -0500 Subject: [PATCH 13/14] Make rubocop happy --- resources/asciidoctor/lib/care_admonition/extension.rb | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/resources/asciidoctor/lib/care_admonition/extension.rb b/resources/asciidoctor/lib/care_admonition/extension.rb index 83f0910343de9..9e82dc15cb7f0 100644 --- a/resources/asciidoctor/lib/care_admonition/extension.rb +++ b/resources/asciidoctor/lib/care_admonition/extension.rb @@ -3,7 +3,7 @@ require 'asciidoctor/extensions' ## -# Extensions for marking when something as `beta`, `dev`, or technical `preview`. +# Extensions for marking something as `beta`, `dev`, or technical `preview`. # # Usage # @@ -13,11 +13,10 @@ # Foo beta:[] # Foo dev:[] # 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 This functionality is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features. From cf4510fc8a757493ef0a7afa8124af7d88ffbc4c Mon Sep 17 00:00:00 2001 From: Greg Back Date: Thu, 20 Jan 2022 15:18:09 -0500 Subject: [PATCH 14/14] Make rubocop happier --- integtest/spec/single_book_spec.rb | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/integtest/spec/single_book_spec.rb b/integtest/spec/single_book_spec.rb index 0ac7a9329bd40..98627a0aa980d 100644 --- a/integtest/spec/single_book_spec.rb +++ b/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 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.' + '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