Skip to content

Commit 5b9adb5

Browse files
v1vv1v
committed
Merge remote-tracking branch 'upstream/master' into feature/beats-neutral-naming
* upstream/master: (28 commits) Fixes .net book generation. (elastic#2367) Add main branch to elasticsearch-net repo to docs build. (elastic#2196) Update attributes.asciidoc (elastic#2365) Note that the full path is required for local doc build (elastic#2364) Bump current version to 7.17 (elastic#2333) moves old file back to bottom add new path for kibana links check apm: Neutral naming for apm-agent-java (elastic#2350) Change current to MS-68 (elastic#2355) Remove unnecessary branch mapping for package-spec (elastic#2359) Adds tech preview macro, updates experimental (elastic#2340) [DOCS] Add `plugins-7x` and `plugins-6x` attributes (elastic#2358) apm: Neutral naming for apm-agent-python (elastic#2348) apm: Neutral naming for apm-agent-rum-js (elastic#2354) apm: Neutral naming for apm-agent-dotnet (elastic#2352) apm: Neutral naming for apm-agent-nodejs (elastic#2353) Neutral naming for apm-agent-go (elastic#2351) apm: Neutral naming for apm-agent-php (elastic#2349) Add 7.last attribute for APM Guide (elastic#2356) [apm] main branch for apm-agent-ruby (elastic#2347) ...
2 parents 8872b20 + c82acc5 commit 5b9adb5

14 files changed

+133
-108
lines changed

‎README.asciidoc

Lines changed: 23 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@ generate the HTML version of the docs:
7070
[source,bash]
7171
----------------------------
7272
cd path/to/your/repo
73-
~/path/to/docs/repo/build_docs --doc path/to/index.asciidoc
73+
~/path/to/docs/repo/build_docs --doc /full/path/to/index.asciidoc
7474
----------------------------
7575

7676
Each Elastic project may need its own documentation book build command.
@@ -1534,9 +1534,9 @@ deprecated::[0.90.4,Replace by `foo.baz`. See <<new-section>>]
15341534
Text about old functionality...
15351535

15361536
[[experimental]]
1537-
== Beta, Dev, and Experimental
1537+
== Beta, Dev, and Preview (experimental)
15381538

1539-
APIs or parameters that are in beta, in development, or experimental can be
1539+
APIs or parameters that are in beta, in development, or in technical preview (formerly experimental) can be
15401540
marked as such, using markup similar to that used in <<changes>>.
15411541

15421542
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.
16241624

16251625
=== Using the `experimental` admonition
16261626

1627+
Experimental language is deprecated.
1628+
1629+
We decided on the much less raw sounding "technical preview".
1630+
1631+
See below.
1632+
1633+
=== Using the technical `preview` admonition
1634+
16271635
[source,asciidoc]
16281636
----
16291637
[[new-feature]]
1630-
=== New experimental feature
1638+
=== New feature in technical preview
16311639
1632-
experimental::[]
1640+
preview::[]
16331641
1634-
experimental::[https://github.com/elastic/docs/issues/505]
1642+
preview::[https://github.com/elastic/docs/issues/505]
16351643
1636-
experimental::[{issue}505]
1644+
preview::[{issue}505]
16371645
1638-
experimental::["Custom text goes here."]
1646+
preview::["Custom text goes here."]
16391647
1640-
experimental::["Custom text goes here.",https://github.com/elastic/docs/issues/505]
1648+
preview::["Custom text goes here.",https://github.com/elastic/docs/issues/505]
16411649
1642-
experimental::["Custom text goes here.",{issue}505]
1650+
preview::["Custom text goes here.",{issue}505]
16431651
16441652
Text about new feature...
16451653
16461654
[[old-feature]]
16471655
=== Established feature
16481656
16491657
This feature has been around for a while, but we're adding
1650-
a new experimental parameter:
1658+
a new preview parameter:
16511659
16521660
`established_param`::
16531661
This param has been around for ages and won't change.
16541662
16551663
`experimental_param`::
1656-
experimental:[]
1657-
This param is experimental and may change in the future.
1664+
preview:[]
1665+
This param is in technical preview and may change in the future.
16581666
16591667
`experimental_param`::
1660-
experimental:["Custom text goes here."]
1661-
This param is experimental and may change in the future.
1668+
preview:["Custom text goes here."]
1669+
This param is in technical preview and may change in the future.
16621670
----
16631671

16641672
[[images]]

‎build_docs.pl

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -422,6 +422,9 @@ sub check_kibana_links {
422422
say " Branch: $branch, Version: $version";
423423
my $links_file;
424424
my $source = eval {
425+
$links_file = "packages/kbn-doc-links/src/get_doc_links.ts";
426+
$repo->show_file( $link_check_name, $branch, $links_file );
427+
} || eval {
425428
$links_file = $src_path . ".js";
426429
$repo->show_file( $link_check_name, $branch, $links_file );
427430
} || eval {

‎conf.yaml

Lines changed: 34 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -71,16 +71,17 @@ contents_title: Elastic Stack and Product Documentation
7171
# <key>: &<variable> <value>
7272
# The keys don't really matter, but by convention the are the same as the variable.
7373
variables:
74-
stackcurrent: &stackcurrent 7.16
75-
stacklive: &stacklive [ master, 8.0, 7.17, 7.16, 6.8 ]
74+
stackcurrent: &stackcurrent 7.17
75+
stacklive: &stacklive [ master, 8.0, 7.17, 6.8 ]
7676

77-
stacklivemain: &stacklivemain [ main, 8.0, 7.17, 7.16, 6.8 ]
77+
stacklivemain: &stacklivemain [ main, 8.0, 7.17, 6.8 ]
7878

79-
cloudSaasCurrent: &cloudSaasCurrent ms-66
79+
cloudSaasCurrent: &cloudSaasCurrent ms-68
8080

8181
mapCloudSaasToClientsTeam: &mapCloudSaasToClientsTeam
8282
*cloudSaasCurrent : master
8383
mapCloudEceToClientsTeam: &mapCloudEceToClientsTeam
84+
ms-65: master
8485
ms-62: master
8586
ms-59: master
8687
ms-57: master
@@ -352,6 +353,7 @@ contents:
352353
repo: elasticsearch-net
353354
path: examples
354355
exclude_branches: [ 7.17, 7.16, 7.15, 7.14, 7.13, 7.12, 7.11, 7.10, 7.9, 7.8, 7.7, 7.6, 7.5, 7.4, 7.3, 7.2, 7.1, 7.0, 6.8, 6.7, 6.6, 6.5, 6.4, 6.3, 6.2, 6.1, 6.0, 5.6, 5.5, 5.4, 5.3, 5.2, 5.1, 5.0, 2.4, 2.3, 2.2, 2.1, 2.0, 1.7, 1.6, 1.5, 1.4, 1.3, 0.90 ]
356+
map_branches: *mapMasterToMain
355357
-
356358
alternatives: { source_lang: console, alternative_lang: python }
357359
repo: elasticsearch-py
@@ -540,10 +542,11 @@ contents:
540542
path: .doc/
541543
- title: .NET Clients
542544
prefix: net-api
545+
# The elasticsearch-net repo only keeps .x branches. Do not
546+
# bump these with the rest of the stack.
543547
current: 7.16
544-
# need to keep 7.x until all tooling is switched over to 7.16
545-
branches: [ master, 8.0, 7.17, 7.16, 7.x, 6.x, 5.x, 2.x, 1.x ]
546-
live: [ master, 8.0, 7.17, 7.16, 7.x ]
548+
branches: [ {main: master}, 8.0, 7.17, 7.16, 7.x, 6.x, 5.x, 2.x, 1.x ]
549+
live: [ main, 8.0, 7.17, 7.16, 7.x ]
547550
index: docs/index.asciidoc
548551
tags: Clients/.Net
549552
subject: Clients
@@ -651,9 +654,9 @@ contents:
651654
exclude_branches: [ 6.2, 6.1, 6.0, 5.6, 5.5, 5.4, 5.3, 5.2, 5.1, 5.0, 2.4, 2.3, 2.2, 2.1, 2.0, 1.7, 1.6, 1.5, 1.4, 1.3, 0.90 ]
652655
- title: Java Transport Client (deprecated)
653656
prefix: java-api
654-
current: *stackcurrent
657+
current: 7.17
655658
branches: [ 7.17, 7.16, 7.15, 7.14, 7.13, 7.12, 7.11, 7.10, 7.9, 7.8, 7.7, 7.6, 7.5, 7.4, 7.3, 7.2, 7.1, 7.0, 6.8, 6.7, 6.6, 6.5, 6.4, 6.3, 6.2, 6.1, 6.0, 5.6, 5.5, 5.4, 5.3, 5.2, 5.1, 5.0, 2.4, 2.3, 2.2, 2.1, 2.0, 1.7, 1.6, 1.5, 1.4, 1.3, 0.90 ]
656-
live: *stacklive
659+
live: [7.17, 6.8]
657660
index: docs/java-api/index.asciidoc
658661
tags: Clients/Java
659662
subject: Clients
@@ -844,8 +847,8 @@ contents:
844847
prefix: en/cloud-enterprise
845848
tags: CloudEnterprise/Reference
846849
subject: ECE
847-
current: ms-62
848-
branches: [ {'ms-62': 2.12}, {'ms-59': 2.11}, {'ms-57': 2.10}, {'ms-53': 2.9}, {'ms-49': 2.8}, {'ms-47': 2.7}, {'release-ms-41': 2.6}, 2.5, 2.4, 2.3, 2.2, 2.1, 2.0, 1.1, 1.0 ]
850+
current: ms-65
851+
branches: [ {'ms-65': 2.13}, {'ms-62': 2.12}, {'ms-59': 2.11}, {'ms-57': 2.10}, {'ms-53': 2.9}, {'ms-49': 2.8}, {'ms-47': 2.7}, {'release-ms-41': 2.6}, 2.5, 2.4, 2.3, 2.2, 2.1, 2.0, 1.1, 1.0 ]
849852
index: docs/cloud-enterprise/index.asciidoc
850853
chunk: 2
851854
private: 1
@@ -861,6 +864,7 @@ contents:
861864
repo: cloud-assets
862865
path: docs
863866
map_branches:
867+
ms-65: master
864868
ms-62: master
865869
ms-59: master
866870
ms-57: master
@@ -934,8 +938,8 @@ contents:
934938
prefix: en/ecctl
935939
tags: CloudControl/Reference
936940
subject: ECCTL
937-
current: 1.6
938-
branches: [ master, 1.6, 1.5, 1.4, 1.3, 1.2, 1.1, 1.0 ]
941+
current: 1.7
942+
branches: [ master, 1.7, 1.6, 1.5, 1.4, 1.3, 1.2, 1.1, 1.0 ]
939943
index: docs/index.asciidoc
940944
chunk: 1
941945
sources:
@@ -1235,16 +1239,16 @@ contents:
12351239
-
12361240
repo: apm-aws-lambda
12371241
path: docs
1238-
exclude_branches: [ 8.0, 7.17, 7.16, 7.15, 7.14, 7.13, 7.12, 7.11, 7.10, 7.9, 7.8, 7.7, 7.6, 7.5, 7.4, 7.3, 7.2, 7.1, 7.0, 6.8, 6.7, 6.6, 6.5, 6.4, 6.3, 6.2, 6.1, 6.0, 5.6, 5.5, 5.4, 5.3, 5.2, 5.1, 5.0 ]
1242+
exclude_branches: [ 7.15, 7.14, 7.13, 7.12, 7.11, 7.10, 7.9, 7.8, 7.7, 7.6, 7.5, 7.4, 7.3, 7.2, 7.1, 7.0, 6.8, 6.7, 6.6, 6.5, 6.4, 6.3, 6.2, 6.1, 6.0, 5.6, 5.5, 5.4, 5.3, 5.2, 5.1, 5.0 ]
12391243
map_branches: *mapMasterToMain
12401244
- title: APM Agents
12411245
base_dir: agent
12421246
sections:
12431247
- title: APM Go Agent
12441248
prefix: go
12451249
current: 1.x
1246-
branches: [ master, 1.x, 0.5 ]
1247-
live: [ master, 1.x ]
1250+
branches: [ {main: master}, 1.x, 0.5 ]
1251+
live: [ main, 1.x ]
12481252
index: docs/index.asciidoc
12491253
tags: APM Go Agent/Reference
12501254
subject: APM
@@ -1276,8 +1280,8 @@ contents:
12761280
- title: APM Java Agent
12771281
prefix: java
12781282
current: 1.x
1279-
branches: [ master, 1.x, 0.7, 0.6 ]
1280-
live: [ master, 1.x ]
1283+
branches: [ {main: master}, 1.x, 0.7, 0.6 ]
1284+
live: [ main, 1.x ]
12811285
index: docs/index.asciidoc
12821286
tags: APM Java Agent/Reference
12831287
subject: APM
@@ -1293,8 +1297,8 @@ contents:
12931297
- title: APM .NET Agent
12941298
prefix: dotnet
12951299
current: 1.12
1296-
branches: [ master, 1.12, 1.11, 1.10, 1.9, 1.8 ]
1297-
live: [ master, 1.12 ]
1300+
branches: [ {main: master}, 1.12, 1.11, 1.10, 1.9, 1.8 ]
1301+
live: [ main, 1.12 ]
12981302
index: docs/index.asciidoc
12991303
tags: APM .NET Agent/Reference
13001304
subject: APM
@@ -1309,8 +1313,8 @@ contents:
13091313
- title: APM Node.js Agent
13101314
prefix: nodejs
13111315
current: 3.x
1312-
branches: [ master, 3.x, 2.x, 1.x, 0.x ]
1313-
live: [ master, 3.x ]
1316+
branches: [ {main: master}, 3.x, 2.x, 1.x, 0.x ]
1317+
live: [ main, 3.x ]
13141318
index: docs/index.asciidoc
13151319
tags: APM Node.js Agent/Reference
13161320
subject: APM
@@ -1326,8 +1330,8 @@ contents:
13261330
- title: APM PHP Agent
13271331
prefix: php
13281332
current: 1.x
1329-
branches: [ master, 1.x ]
1330-
live: [ master, 1.x ]
1333+
branches: [ {main: master}, 1.x ]
1334+
live: [ main, 1.x ]
13311335
index: docs/index.asciidoc
13321336
tags: APM PHP Agent/Reference
13331337
subject: APM
@@ -1342,8 +1346,8 @@ contents:
13421346
- title: APM Python Agent
13431347
prefix: python
13441348
current: 6.x
1345-
branches: [ master, 6.x, 5.x, 4.x, 3.x, 2.x, 1.x ]
1346-
live: [ master, 6.x, 5.x ]
1349+
branches: [ {main: master}, 6.x, 5.x, 4.x, 3.x, 2.x, 1.x ]
1350+
live: [ main, 6.x, 5.x ]
13471351
index: docs/index.asciidoc
13481352
tags: APM Python Agent/Reference
13491353
subject: APM
@@ -1359,8 +1363,8 @@ contents:
13591363
- title: APM Ruby Agent
13601364
prefix: ruby
13611365
current: 4.x
1362-
branches: [ master, 4.x, 3.x, 2.x, 1.x ]
1363-
live: [ master, 4.x ]
1366+
branches: [ {main: master}, 4.x, 3.x, 2.x, 1.x ]
1367+
live: [ main, 4.x ]
13641368
index: docs/index.asciidoc
13651369
tags: APM Ruby Agent/Reference
13661370
subject: APM
@@ -1376,8 +1380,8 @@ contents:
13761380
- title: APM Real User Monitoring JavaScript Agent
13771381
prefix: rum-js
13781382
current: 5.x
1379-
branches: [ master, 5.x, 4.x, 3.x, 2.x, 1.x, 0.x ]
1380-
live: [ master, 5.x, 4.x]
1383+
branches: [ {main: master}, 5.x, 4.x, 3.x, 2.x, 1.x, 0.x ]
1384+
live: [ main, 5.x, 4.x]
13811385
index: docs/index.asciidoc
13821386
tags: APM Real User Monitoring JavaScript Agent/Reference
13831387
subject: APM
@@ -1784,7 +1788,6 @@ contents:
17841788
-
17851789
repo: package-spec
17861790
path: versions
1787-
map_branches: *mapMainToMaster
17881791

17891792
- title: "Beats: Collect, Parse, and Ship"
17901793
sections:

‎integtest/spec/single_book_spec.rb

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -287,7 +287,10 @@
287287
page_context 'chapter.html' do
288288
it 'includes the experimental text' do
289289
expect(body).to include(
290-
'This functionality is experimental and may be changed or removed'
290+
'This functionality is in technical preview and may be changed or '\
291+
'removed in a future release. Elastic will apply best effort to fix '\
292+
'any issues, but features in technical preview are not subject to '\
293+
'the support SLA of official GA features.'
291294
)
292295
end
293296
end

‎resources/asciidoctor/lib/care_admonition/extension.rb

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,19 @@
33
require 'asciidoctor/extensions'
44

55
##
6-
# Extensions for marking when something as `beta`, `dev`, or `experimental`.
6+
# Extensions for marking something as `beta`, `dev`, or technical `preview`.
77
#
88
# Usage
99
#
1010
# beta::[]
1111
# dev::[]
12-
# experimental::[]
12+
# preview::[]
1313
# Foo beta:[]
1414
# Foo dev:[]
15-
# Foo experimental:[]
15+
# Foo preview:[]
16+
#
17+
# !! `experimental:[]` is supported as a deprecated alternative to `preview:[]`.
18+
# !! But please use `preview:[]` instead.
1619
#
1720
class CareAdmonition < Asciidoctor::Extensions::Group
1821
BETA_DEFAULT_TEXT = <<~TEXT.strip
@@ -21,15 +24,16 @@ class CareAdmonition < Asciidoctor::Extensions::Group
2124
DEV_DEFAULT_TEXT = <<~TEXT.strip
2225
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.
2326
TEXT
24-
EXPERIMENTAL_DEFAULT_TEXT = <<~TEXT.strip
25-
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.
27+
PREVIEW_DEFAULT_TEXT = <<~TEXT.strip
28+
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.
2629
TEXT
2730

2831
def activate(registry)
2932
[
3033
[:beta, 'beta', BETA_DEFAULT_TEXT],
3134
[:dev, 'dev', DEV_DEFAULT_TEXT],
32-
[:experimental, 'experimental', EXPERIMENTAL_DEFAULT_TEXT],
35+
[:experimental, 'experimental', PREVIEW_DEFAULT_TEXT],
36+
[:preview, 'preview', PREVIEW_DEFAULT_TEXT],
3337
].each do |(name, role, default_text)|
3438
registry.block_macro ChangeAdmonitionBlock.new(role, default_text), name
3539
registry.inline_macro ChangeAdmonitionInline.new(role, default_text), name

‎resources/asciidoctor/spec/care_admonition_spec.rb

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -247,7 +247,17 @@ def expect_inline_admonition(text)
247247
let(:admon_class) { 'warning' }
248248
let(:default_text) do
249249
<<~TEXT.strip
250-
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.
250+
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.
251+
TEXT
252+
end
253+
include_examples 'care admonition'
254+
end
255+
context 'preview' do
256+
let(:key) { 'preview' }
257+
let(:admon_class) { 'warning' }
258+
let(:default_text) do
259+
<<~TEXT.strip
260+
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.
251261
TEXT
252262
end
253263
include_examples 'care admonition'

0 commit comments

Comments
 (0)