Add more admonitions

Author: lcawl

.rubocop.yml

@@ -37,4 +37,4 @@ Metrics/ClassLength:
   Max: 120
 
 Metrics/MethodLength:
-  Max: 20
+  Max: 35

README.asciidoc

@@ -1399,23 +1399,16 @@ The path should be as specific as possible because we skip rebuilding books if
 changes to the referenced repository don't change the referenced path.
 
 [[changes]]
-== Additions and deprecations
+== Additions, deprecations, and discontinuations
 
-Documentation is built for various branches, eg `0.90`,
-`1.00`, `master`.  However, we release versions
-`0.90.0`, `0.90.1`, etc, which are all based on the
-`0.90` branch.
+When adding, deprecating, or discontinuing functionality, you can mark the change as
+_coming_, _generally available_ (formerly _added_), _deprecated_, or _discontinued_.
 
-When adding new functionality to a branch, or deprecating
-existing functionality, you can mark the change as
-_added_, _coming_ or _deprecated_. Use `coming` when the addition is
-in an as yet unreleased version of the current branch, and `added` when
-the functionality is already released.
-
-The `update_versions.pl` script can be used to change `coming` notices
-to `added` notices when doing a new release, and can also be used
-to remove `added`, `coming` and `deprecated` notices completely.
+Use `coming` when the addition is in an as yet unreleased version of the current branch.
+Use `generally_available` when the functionality is released and no longer in a beta, dev, or preview state.
 
+For Elastic Serverless and Elasticsearch Service content, there currently isn't a public identifier for individual releases.
+In other contexts, you can qualify the addition, deprecation, or discontinuation with a specific version number.
 
 === Inline notifications
 
@@ -1425,33 +1418,20 @@ the addition or deprecation of individual parameters.
 [source,asciidoc]
 ----------------------------------
 [horizontal]
-`foo.bar`::   Does XYZ. added:[0.90.4]
-`foo.bar`::   Does XYZ. coming:[0.90.4]
-`foo.baz`::   Does XYZ. deprecated:[0.90.4]
+`foo.bar`::   Does XYZ. ga_stack:[0.90.4]
+`foo.bar`::   Does XYZ. coming:[0.90.4] coming_serverless:[] coming_ess:[]
+`foo.baz`::   Does XYZ. deprecated:[0.90.4] deprecated_serverless:[] deprecated_ess:[]
 ----------------------------------
 
-[horizontal]
-`foo.bar`::   Does XYZ. added:[0.90.4]
-`foo.bar`::   Does XYZ. coming:[0.90.4]
-`foo.baz`::   Does XYZ. deprecated:[0.90.4]
-
-You can also include details about additional
-notes in the notifications which show up when the
-user hovers over it:
+Some annotations also enable you add custom notes that show up when the user hovers over it:
 
 [source,asciidoc]
 ----------------------------------
 [horizontal]
-`foo.bar`::   Does XYZ. added:[0.90.4,Replaces `foo.baz`]
 `foo.bar`::   Does XYZ. coming:[0.90.4,Replaces `foo.baz`]
 `foo.baz`::   Does XYZ. deprecated:[0.90.4,Replaced by `foo.bar`]
 ----------------------------------
 
-[horizontal]
-`foo.bar`::   Does XYZ. added:[0.90.4,Replaces `foo.baz`]
-`foo.bar`::   Does XYZ. coming:[0.90.4,Replaces `foo.baz`]
-`foo.baz`::   Does XYZ. deprecated:[0.90.4,Replaced by `foo.bar`]
-
 [NOTE]
 ====
 If the details include a comma, you must use quotation marks. For example:
@@ -1463,98 +1443,48 @@ deprecated::[1.1.0,"Span started automatically by <<apm-start-span,apm.startSpan
 
 === Section notifications
 
-Use section notifications to mark an entire chapter or
-section as _added_/_deleted_.  Notifications can just refer
-to the version in which the change was made:
+Use section notifications to annotate an entire page or section. 
 
 [source,asciidoc]
 ----------------------------------
 ==== New section
 
-added::[0.90.4]
+ga_stack::[0.90.4]
 
 Text about new functionality...
 
 ==== New section not yet released
 
-coming::[0.90.9]
+coming_ess::[]
 
 Text about new functionality...
 
 ==== Old section
 
-deprecated::[0.90.4]
+deprecated_serverless::[]
 
 Text about old functionality...
 ----------------------------------
 
-==== New section
-
-added::[0.90.4]
-
-Text about new functionality...
-
-==== New section not yet released
-
-coming::[0.90.9]
-
-Text about new functionality...
-
-==== Old section
-
-deprecated::[0.90.4]
-
-Text about old functionality...
-
-[[with_details]]
-==== With details...
-
-Or they can include extra text, including more
-Asciidoc markup:
+In some cases you can add extra text, including more Asciidoc markup.
+For example:
 
 [source,asciidoc]
 ----------------------------------
-[[new-section]]
-==== New section
-
-added::[0.90.4,Replaces `foo.bar`. See <<old-section>>]
-
-Text about new functionality...
-
 [[coming-section]]
 ==== New section not yet released
 
 coming::[0.90.9,Replaces `foo.bar`. See <<old-section>>]
 
 Text about new functionality...
-
-[[old-section]]
-==== Old section
-
-deprecated::[0.90.4,Replace by `foo.baz`. See <<new-section>>]
-
-Text about old functionality...
 ----------------------------------
 
-[[new-section]]
-==== New section
-
-added::[0.90.4,Replaces `foo.bar`. See <<old-section>>]
-
-Text about new functionality...
-
-[[old-section]]
-==== Old section
-
-deprecated::[0.90.4,Replace by `foo.baz`. See <<new-section>>]
-
-Text about old functionality...
-
 [[experimental]]
 == Beta, Dev, and Preview (experimental)
 
-APIs or parameters that are in beta, in development, or in technical preview (formerly experimental) can be
+Functionality that is in beta, in development, or in technical preview (formerly experimental) can be
 marked as such, using markup similar to that used in <<changes>>.
+Since a feature might be in different lifecycle stages in different contexts, there are multiple variations of each admonition (for example, `beta`, `beta_ess`, and `beta_serverless`).
 
 In the block format, you have the option of adding a related GitHub issue link.
 If both custom text and a GitHub link are provided, the GitHub link **must** be
@@ -1570,15 +1500,15 @@ attribute in place of the GitHub issue link.
 
 beta::[]
 
-beta::[https://github.com/elastic/docs/issues/505]
+beta_serverless::[https://github.com/elastic/docs/issues/505]
 
 beta::[{issue}505]
 
-beta::["Custom text goes here."]
+beta_ess::["Custom text goes here."]
 
 beta::["Custom text goes here.",https://github.com/elastic/docs/issues/505]
 
-beta::["Custom text goes here.",{issue}505]
+beta_serverless::["Custom text goes here.",{issue}505]
 
 Text about new feature...
 
@@ -1592,11 +1522,11 @@ a new parameter that's in beta:
 This param has been around for ages and won't change.
 
 `beta_param`::
-beta:[]
+beta:[] 
 This param is in beta and may change in the future.
 
 `beta_param`::
-beta:["Custom text goes here."]
+beta_serverless:["Custom text goes here."]
 This param is in beta and may change in the future.
 ----
 
@@ -1609,15 +1539,15 @@ This param is in beta and may change in the future.
 
 dev::[]
 
-dev::[https://github.com/elastic/docs/issues/505]
+dev_serverless::[https://github.com/elastic/docs/issues/505]
 
 dev::[{issue}505]
 
-dev::["Custom text goes here."]
+dev_ess::["Custom text goes here."]
 
 dev::["Custom text goes here.",https://github.com/elastic/docs/issues/505]
 
-dev::["Custom text goes here.",{issue}505]
+dev_serverless::["Custom text goes here.",{issue}505]
 
 Text about feature in development...
 
@@ -1635,7 +1565,7 @@ dev:[]
 This param is in development and may change in the future.
 
 `dev_param`::
-dev:["Custom text goes here."]
+dev_ess:["Custom text goes here."]
 This param is in development and may change in the future.
 ----
 
@@ -1656,15 +1586,15 @@ See below.
 
 preview::[]
 
-preview::[https://github.com/elastic/docs/issues/505]
+preview_serverless::[https://github.com/elastic/docs/issues/505]
 
 preview::[{issue}505]
 
-preview::["Custom text goes here."]
+preview_ess::["Custom text goes here."]
 
 preview::["Custom text goes here.",https://github.com/elastic/docs/issues/505]
 
-preview::["Custom text goes here.",{issue}505]
+preview_serverless::["Custom text goes here.",{issue}505]
 
 Text about new feature...
 
@@ -1682,7 +1612,7 @@ preview:[]
 This param is in technical preview and may change in the future.
 
 `experimental_param`::
-preview:["Custom text goes here."]
+preview_ess:["Custom text goes here."]
 This param is in technical preview and may change in the future.
 ----
 

resources/asciidoctor/lib/care_admonition/extension.rb

@@ -3,16 +3,43 @@
 require 'asciidoctor/extensions'
 
 ##
-# Extensions for marking something as `beta`, `dev`, or technical `preview`.
+# Extensions for marking something as `beta`, `beta_serverless`, `beta_ess`,
+# `dev`, `dev_serverless`, `dev_ess`, technical `preview`, `preview_serverless`,
+# `preview_ess`, `ga_serverless`, `ga_ess`.
 #
 # Usage
 #
 #   beta::[]
 #   dev::[]
 #   preview::[]
+#   beta_ess::[]
+#   beta_serverless::[]
+#   dev_ess::[]
+#   dev_serverless::[]
+#   ga_serverless::[]
+#   deprecated_ess::[]
+#   deprecated_serverless::[]
+#   discontinued_ess::[]
+#   discontinued_serverless::[]
+#   coming_ess::[]
+#   coming_serverless::[]
 #   Foo beta:[]
 #   Foo dev:[]
 #   Foo preview:[]
+#   Foo beta_ess:[]
+#   Foo beta_serverless:[]
+#   Foo dev_ess:[]
+#   Foo dev_serverless:[]
+#   Foo preview_ess:[]
+#   Foo preview_serverless:[]
+#   Foo ga_ess:[]
+#   Foo ga_serverless:[]
+#   Foo deprecated_ess:[]
+#   Foo deprecated_serverless:[]
+#   Foo discontinued_ess:[]
+#   Foo discontinued_serverless:[]
+#   Foo coming_ess:[]
+#   Foo coming_serverless::[]
 #
 # !! `experimental:[]` is supported as a deprecated alternative to `preview:[]`.
 # !! But please use `preview:[]` instead.
@@ -21,19 +48,83 @@ 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.
   TEXT
+  BETA_SERVERLESS_TEXT = <<~TEXT.strip
+    This functionality is in beta in Elastic Serverless 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.
+  TEXT
+  BETA_ESS_TEXT = <<~TEXT.strip
+    This functionality is in beta in Elasticsearch Service 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.
+  TEXT
   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
+  DEV_SERVERLESS_TEXT = <<~TEXT.strip
+    This functionality is in development in Elastic Serverless 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
+  DEV_ESS_TEXT = <<~TEXT.strip
+    This functionality is in development in Elasticsearch Service 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 in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
   TEXT
+  PREVIEW_SERVERLESS_TEXT = <<~TEXT.strip
+    This functionality is in technical preview in Elastic Serverless and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
+  TEXT
+  PREVIEW_ESS_TEXT = <<~TEXT.strip
+    This functionality is in technical in preview in Elasticsearch Service and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
+  TEXT
+  DEPRECATED_ESS_TEXT = <<~TEXT.strip
+    This functionality is deprecated in Elasticsearch Service and will be removed in a future release.
+  TEXT
+  DEPRECATED_SERVERLESS_TEXT = <<~TEXT.strip
+    This functionality is deprecated in Elastic Serverless and will be removed in a future release.
+  TEXT
+  DISCONTINUED_ESS_TEXT = <<~TEXT.strip
+    This functionality is discontinued in Elasticsearch Service.
+  TEXT
+  DISCONTINUED_SERVERLESS_TEXT = <<~TEXT.strip
+    This functionality is discontinued in Elastic Serverless.
+  TEXT
+  COMING_ESS_TEXT = <<~TEXT.strip
+    This functionality is coming in Elasticsearch Service.
+  TEXT
+  COMING_SERVERLESS_TEXT = <<~TEXT.strip
+    This functionality is coming in Elastic Serverless.
+  TEXT
+  GA_ESS_TEXT = <<~TEXT.strip
+    This functionality is generally available in Elasticsearch Service.
+  TEXT
+  GA_SERVERLESS_TEXT = <<~TEXT.strip
+    This functionality is generally available in Elastic Serverless.
+  TEXT
 
   def activate(registry)
     [
       [:beta, 'beta', BETA_DEFAULT_TEXT],
+      [:beta_serverless, 'Serverless:beta', BETA_SERVERLESS_TEXT],
+      [:beta_ess, 'ESS:beta', BETA_ESS_TEXT],
       [:dev, 'dev', DEV_DEFAULT_TEXT],
+      [:dev_serverless, 'Serverless:dev', DEV_SERVERLESS_TEXT],
+      [:dev_ess, 'ESS:dev', DEV_ESS_TEXT],
       [:experimental, 'preview', PREVIEW_DEFAULT_TEXT],
       [:preview, 'preview', PREVIEW_DEFAULT_TEXT],
+      [:preview_serverless, 'Serverless:preview', PREVIEW_SERVERLESS_TEXT],
+      [:preview_ess, 'ESS:preview', PREVIEW_ESS_TEXT],
+      [
+        :deprecated_serverless,
+        'Serverless:deprecated',
+        DEPRECATED_SERVERLESS_TEXT,
+      ],
+      [:deprecated_ess, 'ESS:deprecated', DEPRECATED_ESS_TEXT],
+      [
+        :discontinued_serverless,
+        'Serverless:discontinued',
+        DISCONTINUED_SERVERLESS_TEXT,
+      ],
+      [:discontinued_ess, 'ESS:discontinued', DISCONTINUED_ESS_TEXT],
+      [:coming_serverless, 'Serverless:coming', COMING_SERVERLESS_TEXT],
+      [:coming_ess, 'ESS:coming', COMING_ESS_TEXT],
+      [:ga_serverless, 'Serverless:GA', GA_SERVERLESS_TEXT],
+      [:ga_ess, 'ESS:GA', GA_ESS_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