From 68e7fee958dfa18619048902ce7c1b8ec80ce704 Mon Sep 17 00:00:00 2001 From: Eric Beahan Date: Fri, 11 Dec 2020 09:40:20 -0600 Subject: [PATCH 01/10] add github_repo_link attribute --- docs/index.asciidoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/index.asciidoc b/docs/index.asciidoc index f74d7c14e1..55a973a661 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -5,6 +5,8 @@ include::{asciidoc-dir}/../../shared/versions/stack/current.asciidoc[] include::{asciidoc-dir}/../../shared/attributes.asciidoc[] +:ecs_github_repo_link: https://github.com/elastic/ecs/blob/master + [[ecs-reference]] == Overview From 098aa4cd29c2590dcacf40700781c7b8a22d432b Mon Sep 17 00:00:00 2001 From: Eric Beahan Date: Fri, 11 Dec 2020 09:51:52 -0600 Subject: [PATCH 02/10] add docs pages for ECS artifacts --- docs/additional.asciidoc | 1 + docs/artifacts.asciidoc | 6 ++++++ 2 files changed, 7 insertions(+) create mode 100644 docs/artifacts.asciidoc diff --git a/docs/additional.asciidoc b/docs/additional.asciidoc index d42bcfbeec..12038289ea 100644 --- a/docs/additional.asciidoc +++ b/docs/additional.asciidoc @@ -9,3 +9,4 @@ include::faq.asciidoc[] include::glossary.asciidoc[] include::contributing.asciidoc[] +include::artifacts.asciidoc[] diff --git a/docs/artifacts.asciidoc b/docs/artifacts.asciidoc new file mode 100644 index 0000000000..3b1455c923 --- /dev/null +++ b/docs/artifacts.asciidoc @@ -0,0 +1,6 @@ +[[ecs-artifacts]] +== Experimental Artifacts + +ECS maintains a collection of experimental artifacts. The ECS artifacts are various files generated directly based on the ECS schema, such as index templates and CSV files. Users can also generate their own custom artifacts using the scripts also available in the project's repo. + +The artifacts can be found in the {ecs_github_repo_link}/generated#artifacts-generated-from-ecs ECS Github repo. From 6a2e13729f0fdacb49ccedf8b2b89aaff203d4cd Mon Sep 17 00:00:00 2001 From: Eric Beahan Date: Fri, 11 Dec 2020 09:52:45 -0600 Subject: [PATCH 03/10] correct hierarchy --- docs/artifacts.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/artifacts.asciidoc b/docs/artifacts.asciidoc index 3b1455c923..51f8810fc9 100644 --- a/docs/artifacts.asciidoc +++ b/docs/artifacts.asciidoc @@ -1,5 +1,5 @@ [[ecs-artifacts]] -== Experimental Artifacts +=== Experimental Artifacts ECS maintains a collection of experimental artifacts. The ECS artifacts are various files generated directly based on the ECS schema, such as index templates and CSV files. Users can also generate their own custom artifacts using the scripts also available in the project's repo. From ebda5cfb5fe8d7fa7af4457fafae084c887616af Mon Sep 17 00:00:00 2001 From: Eric Beahan Date: Fri, 11 Dec 2020 09:53:06 -0600 Subject: [PATCH 04/10] add a link --- docs/additional.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/additional.asciidoc b/docs/additional.asciidoc index 12038289ea..f6796174d8 100644 --- a/docs/additional.asciidoc +++ b/docs/additional.asciidoc @@ -4,6 +4,7 @@ * <> * <> * <> +* <> // include::use-cases.asciidoc[] include::faq.asciidoc[] From 9a9bda6edb37d9a4691bb3dd8254ccee368436ad Mon Sep 17 00:00:00 2001 From: Eric Beahan Date: Fri, 11 Dec 2020 09:53:51 -0600 Subject: [PATCH 05/10] fix anchor --- docs/artifacts.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/artifacts.asciidoc b/docs/artifacts.asciidoc index 51f8810fc9..e6243d6d27 100644 --- a/docs/artifacts.asciidoc +++ b/docs/artifacts.asciidoc @@ -3,4 +3,4 @@ ECS maintains a collection of experimental artifacts. The ECS artifacts are various files generated directly based on the ECS schema, such as index templates and CSV files. Users can also generate their own custom artifacts using the scripts also available in the project's repo. -The artifacts can be found in the {ecs_github_repo_link}/generated#artifacts-generated-from-ecs ECS Github repo. +The artifacts can be found in the {ecs_github_repo_link}/generated#artifacts-generated-from-ecs[ECS Github repo]. From c8e9b4d015e372fa559dcdf114ba956e0aeb3615 Mon Sep 17 00:00:00 2001 From: Eric Beahan Date: Fri, 11 Dec 2020 10:00:12 -0600 Subject: [PATCH 06/10] tweaks --- docs/artifacts.asciidoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/artifacts.asciidoc b/docs/artifacts.asciidoc index e6243d6d27..b6e6af8017 100644 --- a/docs/artifacts.asciidoc +++ b/docs/artifacts.asciidoc @@ -1,6 +1,8 @@ [[ecs-artifacts]] -=== Experimental Artifacts +=== ECS Experimental Artifacts -ECS maintains a collection of experimental artifacts. The ECS artifacts are various files generated directly based on the ECS schema, such as index templates and CSV files. Users can also generate their own custom artifacts using the scripts also available in the project's repo. +ECS maintains a collection of experimental artifacts. These artifacts are various files generated directly based on the ECS schema, such as index templates and CSV files. The artifacts can be found in the {ecs_github_repo_link}/generated#artifacts-generated-from-ecs[ECS Github repo]. + +Users can generate their own custom artifacts using the project's tooling. See the ECS tooling {ecs_github_repo_link}/USAGE.md[usage documentation] for more detail. From e6cc94069271a428b398a9124ac9eb4484c8e64f Mon Sep 17 00:00:00 2001 From: Eric Beahan Date: Fri, 11 Dec 2020 10:04:34 -0600 Subject: [PATCH 07/10] link conventions to new page --- docs/using-conventions.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/using-conventions.asciidoc b/docs/using-conventions.asciidoc index 2972a0df68..f321b26765 100644 --- a/docs/using-conventions.asciidoc +++ b/docs/using-conventions.asciidoc @@ -42,7 +42,7 @@ Elasticsearch can index text using datatypes: ===== Default Elasticsearch convention for indexing text fields Unless your index mapping or index template specifies otherwise -(as the ECS index template does), +(as the <> does), Elasticsearch indexes a text field as `text` at the canonical field name, and indexes a second time as `keyword`, nested in a multi-field. From 3ce9750e1bcc2b991886a68bf2c01aa20d68194f Mon Sep 17 00:00:00 2001 From: Eric Beahan Date: Fri, 11 Dec 2020 10:08:10 -0600 Subject: [PATCH 08/10] add changelog --- CHANGELOG.next.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.next.md b/CHANGELOG.next.md index ef8d6fef4e..ac1d4673ff 100644 --- a/CHANGELOG.next.md +++ b/CHANGELOG.next.md @@ -54,6 +54,7 @@ Thanks, you're awesome :-) --> * Added a notice highlighting that the `tracing` fields are not nested under the namespace `tracing.` #1162 * ES 6.x template data types will fallback to supported types. #1171, #1176, #1186 +* Add a documentation page discussing the experimental artifacts. #1189 #### Deprecated From a266039dd15a33123effd342b9e60cf4a37815a6 Mon Sep 17 00:00:00 2001 From: Eric Beahan Date: Mon, 14 Dec 2020 16:46:28 -0600 Subject: [PATCH 09/10] remove experimental wording --- docs/artifacts.asciidoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/artifacts.asciidoc b/docs/artifacts.asciidoc index b6e6af8017..5129ef3dc0 100644 --- a/docs/artifacts.asciidoc +++ b/docs/artifacts.asciidoc @@ -1,8 +1,8 @@ [[ecs-artifacts]] -=== ECS Experimental Artifacts +=== Generated Artifacts -ECS maintains a collection of experimental artifacts. These artifacts are various files generated directly based on the ECS schema, such as index templates and CSV files. +ECS maintains a collection of artifact files generated directly from the ECS schema, including index templates and CSV files. The artifacts can be found in the {ecs_github_repo_link}/generated#artifacts-generated-from-ecs[ECS Github repo]. -Users can generate their own custom artifacts using the project's tooling. See the ECS tooling {ecs_github_repo_link}/USAGE.md[usage documentation] for more detail. +Users can generate custom artifacts, unique for their own deployments, using the project's tooling. See the ECS tooling {ecs_github_repo_link}/USAGE.md[usage documentation] for more detail. From 9839e9825f9e687cb0b25dfe58929c5df43becdc Mon Sep 17 00:00:00 2001 From: Eric Beahan Date: Mon, 14 Dec 2020 17:01:29 -0600 Subject: [PATCH 10/10] further reworking --- docs/artifacts.asciidoc | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/artifacts.asciidoc b/docs/artifacts.asciidoc index 5129ef3dc0..77df53de17 100644 --- a/docs/artifacts.asciidoc +++ b/docs/artifacts.asciidoc @@ -1,8 +1,6 @@ [[ecs-artifacts]] === Generated Artifacts -ECS maintains a collection of artifact files generated directly from the ECS schema, including index templates and CSV files. +ECS maintains a collection of artifacts which are generated based on the schema. Examples include Elasticsearch index templates, CSV, and Beats field mappings. The maintained artifacts can be found in the {ecs_github_repo_link}/generated#artifacts-generated-from-ecs[ECS Github repo]. -The artifacts can be found in the {ecs_github_repo_link}/generated#artifacts-generated-from-ecs[ECS Github repo]. - -Users can generate custom artifacts, unique for their own deployments, using the project's tooling. See the ECS tooling {ecs_github_repo_link}/USAGE.md[usage documentation] for more detail. +Users can generate custom versions of these artifacts using the ECS project's tooling. See the tooling {ecs_github_repo_link}/USAGE.md[usage documentation] for more detail.