Skip to content

Draft some new admonitions #3085

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

Draft some new admonitions #3085

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e719ddb
Add more admonitions
lcawl Nov 7, 2024
e5cffe2
Use term: Elastic Cloud Serverless
leemthompo Nov 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .rubocop.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,4 +37,4 @@ Metrics/ClassLength:
Max: 120

Metrics/MethodLength:
Max: 20
Max: 35
134 changes: 32 additions & 102 deletions README.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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:
Expand All @@ -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
Expand All @@ -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...

Expand All @@ -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.
----

Expand All @@ -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...

Expand All @@ -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.
----

Expand All @@ -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...

Expand All @@ -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.
----

Expand Down
93 changes: 92 additions & 1 deletion resources/asciidoctor/lib/care_admonition/extension.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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 Cloud 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 Cloud 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 Cloud 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 Cloud 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 Cloud Serverless.
TEXT
Comment on lines +75 to +86
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the difference between deprecated and discontinued? Can we make the discontinued description more specific?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We haven't had "discontinued" before but it arose in discussions like elastic/kibana#192292. Currently we just remove content when the pertinent feature goes from "deprecated" to discontinued/removed/no longer available. If our pages span multiple versions, however, or if we want to give folks a clear indication of when a feature will be removed, it seems like this might be something we'll want to have a way of calling out.

COMING_ESS_TEXT = <<~TEXT.strip
This functionality is coming in Elasticsearch Service.
TEXT
COMING_SERVERLESS_TEXT = <<~TEXT.strip
This functionality is coming in Elastic Cloud 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 Cloud 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
Expand Down
Loading