From 868382463bffa0895ac1527559cad60fcaadfc9c Mon Sep 17 00:00:00 2001 From: Norrie Taylor Date: Wed, 27 Mar 2024 20:17:09 -0700 Subject: [PATCH] Special guidance for ECS contribtions during ECS donation --- CHANGELOG.next.md | 2 ++ CONTRIBUTING.md | 56 ++++++++++++++++++++++++++++++++++++++++++----- README.md | 9 ++++++++ 3 files changed, 62 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.next.md b/CHANGELOG.next.md index b67cd5af89..7c3a382ac5 100644 --- a/CHANGELOG.next.md +++ b/CHANGELOG.next.md @@ -32,6 +32,8 @@ Thanks, you're awesome :-) --> #### Added +* Documentation in README.md providing instruction on contributions to ECS during the OTel donation + #### Improvements #### Deprecated diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0e9c40ddce..b88bbd602c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,7 +7,8 @@ ECS is an open source project and we love to receive contributions from our comm ## Table of Contents -- [How to Contribute](#how-to-contribute) +- [How to contribute](#how-to-contribute) +- - [Special guidance during OTel donation of ECS](#special-guidance-during-otel-donation-of-ecs) - [Dev Tools](#dev-tools) - [Submitting Changes](#submitting-changes) - [Git and Github Guidelines](#git-and-github-guidelines) @@ -22,12 +23,57 @@ ECS is an open source project and we love to receive contributions from our comm - [Schema Files](#schema-files) - [Additional Resources](#additional-resources) -## How to Contribute -There are two primary ways in which you can contribute to ECS. +## How to contribute -1. The [RFC process](./rfcs/README.md) is used for significant additions or breaking changes to the schema itself. -2. For bug fixes or incremental, non-controversial additions to ECS, changes can be made directly to the ECS project and submitted as pull request. +## ECS Donation to OpenTelemetry +In April 2023, OpenTelemetry and Elastic made an [important joint announcement](https://opentelemetry.io/blog/2023/ecs-otel-semconv-convergence/). In this announcement Elastic +shared its intention to achieve convergence of ECS and OTel Semantic Conventions into a single standard maintained +by OpenTelemetry. + +The stated plan has been to keep ECS in a frozen state during the transition. However, it is also apparent that these +things take time. It takes time for the OTel community to adopt donated fields, and it will take time for development +teams to build OTel native constructs in the Elastic stack. In the meantime, our internal and external ECS users need +to be able to develop features for Elastic that rely on continued contributions to the schemas that drive our +technology. + +For these reasons, we need a process and guidelines for contributing to these data schemas during this period that +allows us to avoid breaking changes. + +### How to contribute during OTel donation of ECS + +Bug fixes or minor field addition changes can be made directly to the ECS project and submitted as pull requests. + +Significant changes that add new use cases, top-level fieldsets, or could be considered controversial are +considered material. The general rule for contributing new material changes to schemas during the transition period is + +- First, merge a pull request to OTel with new fields, namespaces or schemas +- Second, to backport those changes to ECS at the ECS starting point indicated below +- Finally, once the Semantic Conventions changes are marked as stable, remove the Beta designation in ECS + +This will ensure that the latest changes are included in OTel Semantic Conventions, where schema evolution will continue +as the merger proceeds. It will also allow teams and users to continue using ECS while OTel migration tools and guidance +are being developed. Finally, this will reduce the risk of breaking changes if new fields are merged first to ECS, and +then require changes before being adopted in Semantic Conventions. + +_There are some exceptions to this rule._ + +1. My contribution to OTel Semantic Conventions is stalled. We are waiting for a sign-off from a second company. +In the meantime, our Elastic feature is blocked. +2. I want to build a workflow in Elastic, and the fields I need to proceed are already in OTel but not in ECS where I +need them today. + +In these cases, the recommendation is to make a contribution to ECS to unblock development. The appropriate ECS starting +point can be an [RFC](./rfcs/README.md) or pull request based on the maturity of the Otel changes. Please see the +following table. + +| OTel submission maturity | Breaking changes expected | ECS starting point | +|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------|------------------------------------------------------| +| OTel working groups accepts the premise of the addition and commits to considering this proposal as it advances. | Major | RFC Stage 1 | +| The initial field definitions comprehensively model the addition to the schema. Fundamental questions and concerns are resolved, though some less significant questions remain open. | Iterative | RFC Stage 2 | +| All requested changes from codeowners have been addressed, and there are no open discussions. | Iterative | Open an ECS pull request with new fields marked Beta | +| Fields, schema, namespace exists in OTel and are designated experimental | Iterative | Open an ECS pull request with new fields marked Beta | +| Fields, schema, namespace exists in OTel and are designated stable | None | Open an ECS pull request with new fields marked GA | ### Dev Tools diff --git a/README.md b/README.md index 16cf9e4125..5b7d78fc5c 100644 --- a/README.md +++ b/README.md @@ -9,9 +9,18 @@ ingesting data into Elasticsearch. A common schema helps you correlate data from sources like logs and metrics or IT operations analytics and security analytics. +## ECS Donation to OpenTelemetry +In April 2023, OpenTelemetry and Elastic made an +[important joint announcement](https://opentelemetry.io/blog/2023/ecs-otel-semconv-convergence/). +In this announcement, we shared our intention to achieve convergence of ECS and OTel +Semantic Conventions into a single standard maintained by OpenTelemetry. + +Special guidance is provided during the donation period. Please review the [contribution guide](CONTRIBUTING.md). + ## Documentation The ECS reference is published on the main Elastic documentation website. + Visit [the official ECS Reference Documentation](https://www.elastic.co/guide/en/ecs/current/index.html). ## Getting Started