From 20d9516889b146402577be4f6a1abc33826dea42 Mon Sep 17 00:00:00 2001 From: Kylie Meli Date: Fri, 3 Apr 2026 14:53:38 -0400 Subject: [PATCH 1/9] Streamline RFC process from four stages to a single Proposal stage --- CHANGELOG.next.md | 1 + rfcs/0000-rfc-template.md | 62 +++++------------ rfcs/PROCESS.md | 65 +++++++++--------- rfcs/README.md | 39 +++-------- stages.html | 136 -------------------------------------- 5 files changed, 61 insertions(+), 242 deletions(-) delete mode 100644 stages.html diff --git a/CHANGELOG.next.md b/CHANGELOG.next.md index 55b21f5ac1..28b0d203ea 100644 --- a/CHANGELOG.next.md +++ b/CHANGELOG.next.md @@ -30,6 +30,7 @@ Thanks, you're awesome :-) --> #### Improvements +* Streamline RFC process from four stages (Strawperson, Draft, Candidate, Finished) to a single Proposal stage with target maturity. #XXXX * Increase composable template `total_fields.limit` from 2000 to 2500. #2584 #### Deprecated diff --git a/rfcs/0000-rfc-template.md b/rfcs/0000-rfc-template.md index 1ac7c95052..0fa5e1617b 100644 --- a/rfcs/0000-rfc-template.md +++ b/rfcs/0000-rfc-template.md @@ -1,60 +1,44 @@ # 0000: Name of RFC - + -- Stage: **0 (strawperson)** -- Date: **TBD** +- Stage: **Proposal** +- Date: **TBD** +- Target maturity: **alpha | beta** - - - +## Summary ## Fields +If the changes include field additions or modifications, please create a folder titled as the RFC number under rfcs/text/. This is where proposed schema changes as standalone YAML files or extended example mappings and larger source documents should go. - ## Usage ## Source data - - - - ## Scope of impact - - +Identify potential concerns, implementation challenges, or complexity. Spend some time on this. Play devil's advocate. Try to identify the sort of non-obvious challenges that tend to surface later. The goal here is to surface risks early, allow everyone the time to work through them, and ultimately document resolution for posterity's sake. - ## People @@ -82,7 +60,7 @@ The following are the people that consulted on the contents of this RFC. * TBD | author - ## References ### RFC Pull Requests - - -* Stage 0: https://github.com/elastic/ecs/pull/NNN - - +* Proposal: https://github.com/elastic/ecs/pull/NNN diff --git a/rfcs/PROCESS.md b/rfcs/PROCESS.md index d628b9b062..ed912a4b4b 100644 --- a/rfcs/PROCESS.md +++ b/rfcs/PROCESS.md @@ -1,14 +1,20 @@ -# Proposing material changes to ECS +# Proposing changes to ECS -Changes to ECS are proposed as Requests for Comments (RFC) in [rfcs/](./) and iterated on through a series of [stages](https://elastic.github.io/ecs/stages.html). To advance to a specific stage, an RFC must meet the documented requirements for that stage. After being accepted into a given stage, there are stage-specific expectations and goals to be met. The overall goal of this process is to thoroughly evaluate and verify the assumptions being made about a change before formally committing it to the schema. +Changes to ECS are proposed as Requests for Comments (RFCs) in [rfcs/](./). A contributor opens a single **Proposal** pull request that is reviewed holistically by the ECS committee. The goal is to thoroughly evaluate and verify the assumptions being made about a change before committing it to the schema. -Each RFC is represented as a markdown document following a prescribed template that gets committed to the repo. Each stage of the RFC is represented as a pull request against that document. +Each RFC is a markdown document following the [template](./0000-rfc-template.md). If the RFC proposes new or changed fields, it should also include a corresponding folder (named after the RFC number) in [rfcs/text/](./text/) containing the proposed schema changes as standalone YAML files or extended example mappings and larger source documents. -If proposing new fields or changing existing fields, the RFC should also have a corresponding folder (named after the RFC number) in [rfcs/text/](./text/). The folder should contain the proposed schema changes as standalone YAML files or extended example mappings and larger source documents. +## How a Proposal works -Generally speaking, the ECS team will help steward the process, but the work of researching and iterating on aspects of an RFC will be owned by that RFC's contributor. If an RFC is being contributed by a community member, then someone at Elastic will need to act as a sponsor of the change to act as a long term owner after completion of the process. The ECS team can help community users with identifying an internal sponsor. If it's not obvious who such a sponsor might be, then the ECS committee will assign a sponsor. +1. A contributor copies the [RFC template](./0000-rfc-template.md), fills in all sections, and opens a pull request. +2. The contributor specifies a **target maturity** of **alpha** or **beta** for the proposed fields. See [Field stability](../docs/reference/ecs-principles-design.md#_field_stability) for definitions. +3. The ECS committee reviews the proposal in a single pass, evaluating the key questions below. +4. On approval the committee merges the PR, and the ECS team assigns a unique RFC number. +5. The proposed fields are added to the schema at the accepted maturity level (by the contributor or the ECS team). -## Key questions we seek to answer through RFC process +GA promotion is handled separately through the field lifecycle process and does not require a new RFC. If a proposal is no longer being pursued, the PR is simply closed. + +## Key questions * Is this change appropriate for ECS? * Does this change provide enough utility for its intended use cases? @@ -16,38 +22,33 @@ Generally speaking, the ECS team will help steward the process, but the work of * Is ownership for the ongoing maintenance of this change clearly defined and accepted? * Is the scope of impact of this change to ingestion, existing applications, and the ECS project itself understood? * Are the technical details of the change defined clearly enough to implement in the schema? -* Are we confident these changes can be stable upon release without requiring revisions or breaking changes? -* Have our assumptions about the shape and utility of these changes been verified by real-world, production-ready usage? - -## Goals with this contributing process - -* Allow contributors to quickly iterate and receive feedback on their fields in a transparent way without the high bar set for general availability in the schema -* Clarify the level of stability to expect from a change in ECS while still allowing early adopters to try it out and provide feedback -* Offer assurance that once an RFC reaches stage 3, we're able to guarantee backward compatibility +* Are we confident these changes can be stable at the proposed maturity level? -## Responsibilities in this process +## Responsibilities Member(s) of the **ECS committee**: -* evaluates whether the changes are appropriate in terms of the goals of the ECS project -* provides recommendations on which common fields would be best suited for reuse versus adding new fields -* determines whether each RFC is accepted into the next target stage by merging the RFC PR +* evaluate whether the changes are appropriate in terms of the goals of the ECS project +* provide recommendations on which common fields would be best suited for reuse versus adding new fields +* determine the accepted maturity level (alpha or beta) and merge the Proposal PR The **ECS team**: -* provides procedural guidance for moving an RFC through stages -* curates the overall RFC process, including closing stalled or abandoned RFCs -* reports on the status of open RFCs -* acts on behalf of the committee for some but not all PRs -* helps community users identify a sponsor at Elastic +* provide procedural guidance for contributors +* curate the RFC process, including closing stalled or abandoned RFCs +* report on the status of open RFCs +* act on behalf of the committee for some but not all PRs +* help community users identify a sponsor at Elastic The **contributor**: -* takes responsibility for doing all necessary legwork to move their RFC forward including but not limited to responding to feedback, identifying and bringing in subject matter experts, and researching the scope of impact -* demonstrates how the fields in the RFC are expected to be used: from the data source, all the way to its consumption -* commits to iterating on the RFCs through to stage 3 if necessary -* creates and iterate on RFC PRs -* implements all necessary changes to their RFC PRs +* take responsibility for the legwork required to move their RFC forward, including responding to feedback, identifying and bringing in subject matter experts, and researching the scope of impact +* demonstrate how the proposed fields are expected to be used, from data source through to consumption +* create and iterate on the Proposal PR The **sponsor** at Elastic: -* can be the same person as the contributor if they're someone at Elastic that can take ownership of this change through membership on the ECS committee -* is involved at least from stage 1 onward if a different person than the contributor -* signs off on each stage if a different person than the contributor -* takes or coordinates ownership of the addition in terms of support and maintenance after the RFC process is completed +* can be the same person as the contributor if they are an Elastic employee who can take ownership through committee membership +* sign off on the proposal if a different person than the contributor +* take or coordinate ownership of the addition in terms of support and maintenance after the RFC process is completed + +## Planned work + +* **Automated schema implementation**: on merge of a Proposal PR, automatically apply the proposed field definitions to the schema. +* **Automated field promotion**: automatically promote fields from beta to GA once an adoption threshold is met. diff --git a/rfcs/README.md b/rfcs/README.md index 2efd0e9ea8..298e1d2ff1 100644 --- a/rfcs/README.md +++ b/rfcs/README.md @@ -1,8 +1,8 @@ # Elastic Common Schema RFCs -While smaller and less controversial changes can still be made directly through pull requests, more substantial changes follow a multi-stage RFC process to ensure they are sufficiently thought out and vetted before being released for general availability in the schema. +While smaller and less controversial changes can still be made directly through pull requests, more substantial changes follow the RFC process to ensure they are sufficiently thought out and vetted before being added to the schema. -The types of changes that warrant this RFC process include but are not limited to: +The types of changes that warrant an RFC include but are not limited to: * Breaking changes targeting the next major version * New top level fieldsets @@ -11,35 +11,18 @@ The types of changes that warrant this RFC process include but are not limited t Check out [Proposing Changes](./PROCESS.md) for high level information about the RFC process. -Check out the [series of stages](https://elastic.github.io/ecs/stages.html) an RFC will go through to be fully vetted. - ## How this works -It's important to understand the overall goals and intentions of the RFC process, so it is recommended that you read this and the document listed above. When you're ready to dive in, - -1. Create a new RFC document from the RFC template (described below) -2. Fill in the details for your strawperson -3. Open a PR to commit your RFC to [rfcs/](./) -4. ECS committee and/or team members review -5. ECS committee and/or team member merges RFC, formally accepting the strawperson -6. Expand existing RFC document with additional details -7. Open a PR to commit your proposed changes to the RFC and advance to stage 1 -8. ECS committee and/or team members review -9. ECS committee and/or team member merges RFC, formally accepting the proposal -10. Repeat steps 6-9 for stages 2 and 3 - -## Using the RFC template - -All new RFCs should be started by copying [0000-rfc-template.md](./0000-rfc-template.md) with a name format of `0000-.md`. When the first RFC stage is accepted, the ECS team will assign a unique RFC number, which will identify this RFC throughout all stages of the process. - -Throughout the RFC template are comments that provide guidance on what type of content to include in each stage. It's ideal if you remove comments from your RFC as you fill out the content and they become obsolete. A pristine, finished RFC will have no explanatory comments remaining. - -For the most part, content is additive as you move through the stages. Occasionally, advancing a stage will require modifying existing content. This is OK! This process should be iterative, and the RFC document is considered living until it is finished (i.e. accepted as stage 3). +1. Copy the [RFC template](./0000-rfc-template.md) with a name format of `0000-.md`. +2. Fill in all sections of the template, including the target maturity (alpha or beta) for the proposed fields. +3. Open a PR to commit your RFC to [rfcs/](./). +4. The ECS committee reviews the proposal and provides feedback. +5. On approval the committee merges the PR, and the ECS team assigns a unique RFC number. -## Skipping stages +If the RFC includes field additions or modifications, create a folder named after the RFC number under [rfcs/text/](./text/). This is where proposed schema changes as standalone YAML files, extended example mappings, and larger source documents should go. -While advancing through multiple stages at a time is possible if all the necessary information is provided and thoroughly vetted, moving changes through stage by stage provides the greatest opportunity to iterate efficiently on changes and a much lower chance of an author wasting a ton of their time. +Throughout the RFC template are comments that provide guidance on what to include. Remove comments as you fill out the content and they become obsolete. A finished RFC will have no explanatory comments remaining. -## Abandoning RFCs +## Closing an RFC -If an RFC proposed change is no longer being pursued or has been inactive for an extended time period, the RFC should be assigned to stage X. +If a proposed change is no longer being pursued or has been inactive for an extended period, the PR should be closed. diff --git a/stages.html b/stages.html deleted file mode 100644 index 03d3844e2d..0000000000 --- a/stages.html +++ /dev/null @@ -1,136 +0,0 @@ - - - - - -ECS Proposal Stages - -

ECS Proposal Stages

- -

These are the stages that an individual RFC advances through before being released for general availability in the Elastic Common Schema (ECS). See the Contributing Guide for broader details about contributing changes to ECS through the RFC process. - - - - - - - - - - - - - - - - - - - - - - -
- Stage - Goals during this stage - Criteria for consideration for this stage - Acceptance into this stage signifies - Acceptable changes to schema in this stage - Breaking changes expected after acceptance into this stage - Recommended types of usage implementation -
0 - Strawperson - -
    -
  • Discuss with domain or subject matter experts the utility of these changes -
  • Discuss with ECS team whether these changes seem appropriate for ECS -
- 		Opened RFC pull request for this strawperson at elastic/ecs - The premise of these changes is not obviously useless or inappropriate for ECS - None - Major - N/A -
1 - Draft - -
    -
  • Make the case for these changes -
  • Describe the field definitions at a high level -
  • Identify potential challenges and areas that need more clarity -
- 		-
    -
  • Opened pull request for this proposal revising the existing strawperson -
  • Identified "sponsor" at Elastic who will participate in RFC process and take ownership of the change after the process completes -
  • Outlined initial field definitions -
  • High-level description of examples of usage -
  • High-level description of example sources of data -
  • Identified potential concerns and implementation challenges/complexity -
  • Subject matter experts identified and weighed in on the high level utility of these changes in the pull request -
  • ECS team weighed in on appropriateness of these changes in the pull request -
- 		ECS team accepts the premise of the addition and commits to considering this proposal as it advances. - Draft field definitions can be committed to the ECS schema as "experimental" fields - Major - Proof of concepts, demos -
2 - Candidate - Identify a comprehensive set of field definitions that could be appropriate for real-world usage - -
    -
  • Opened pull request for this draft revising the existing proposal -
  • Completed field definitions -
  • Included a real world example source document -
  • Identifies scope of impact of changes to ingestion mechanisms (e.g. beats/logstash), usage mechanisms (e.g. Kibana applications, detections), and the ECS project (e.g. docs, tooling) -
  • Subject matter experts weighed in on technical utility of field definitions in the pull request -
- 		The initial field definitions comprehensively model the addition to the schema. Fundamental questions and concerns are resolved, though some less significant questions remain open. - Candidate field definitions can be committed to the ECS schema as "beta" fields - Iterative - Experimental features -
3 - Finished - Indicate that the addition is ready for GA release in ECS - -
    -
  • Opened pull request for this candidate revising the existing candidate -
  • Included multiple real world example source documents -
  • Existing or newly raised questions and concerns are addressed -
  • No objections from sponsor, ECS team, or subject matter experts -
- 		There are no further open questions or unaddressed concerns, and the field definitions are complete based on the information and usage experience we have. - Field definitions can be committed to the ECS schema as "GA" fields - None outside major versions - Any -
X - Abandoned - The changes are no longer being actively pursued. - -
    -
  • Opened pull request revising the existing proposal -
  • Describe why the proposed changes are being abandoned -
- 		The proposal will no longer advance. - Any candidate field definitions will be removed from the ECS schema. - N/A - N/A -
From c826a38a98ca4075f3669704980b8cecf8d91041 Mon Sep 17 00:00:00 2001 From: Kylie Meli Date: Mon, 6 Apr 2026 11:03:17 -0400 Subject: [PATCH 2/9] Update CHANGELOG.next.md Co-authored-by: Andrew Kroh --- CHANGELOG.next.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.next.md b/CHANGELOG.next.md index 28b0d203ea..90c2f380f8 100644 --- a/CHANGELOG.next.md +++ b/CHANGELOG.next.md @@ -30,7 +30,7 @@ Thanks, you're awesome :-) --> #### Improvements -* Streamline RFC process from four stages (Strawperson, Draft, Candidate, Finished) to a single Proposal stage with target maturity. #XXXX +* Streamline RFC process from four stages (Strawperson, Draft, Candidate, Finished) to a single Proposal stage with target maturity. #2600 * Increase composable template `total_fields.limit` from 2000 to 2500. #2584 #### Deprecated From 55e3893fab7db0c3942344ccc3bf85a532d53d96 Mon Sep 17 00:00:00 2001 From: Kylie Meli Date: Mon, 6 Apr 2026 14:35:02 -0400 Subject: [PATCH 3/9] move planned items into steps directly as notes --- rfcs/PROCESS.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/rfcs/PROCESS.md b/rfcs/PROCESS.md index ed912a4b4b..6b4b03625f 100644 --- a/rfcs/PROCESS.md +++ b/rfcs/PROCESS.md @@ -10,9 +10,9 @@ Each RFC is a markdown document following the [template](./0000-rfc-template.md) 2. The contributor specifies a **target maturity** of **alpha** or **beta** for the proposed fields. See [Field stability](../docs/reference/ecs-principles-design.md#_field_stability) for definitions. 3. The ECS committee reviews the proposal in a single pass, evaluating the key questions below. 4. On approval the committee merges the PR, and the ECS team assigns a unique RFC number. -5. The proposed fields are added to the schema at the accepted maturity level (by the contributor or the ECS team). +5. The proposed fields are added to the schema at the accepted maturity level (by the contributor or the ECS team). This step will be automated in the future so that field definitions are applied to the schema on merge of the Proposal PR. -GA promotion is handled separately through the field lifecycle process and does not require a new RFC. If a proposal is no longer being pursued, the PR is simply closed. +GA promotion is handled separately through the field lifecycle process and does not require a new RFC. In the future, fields will be automatically promoted from beta to GA once an adoption threshold is met. If a proposal is no longer being pursued, the PR is simply closed. ## Key questions @@ -47,8 +47,3 @@ The **sponsor** at Elastic: * can be the same person as the contributor if they are an Elastic employee who can take ownership through committee membership * sign off on the proposal if a different person than the contributor * take or coordinate ownership of the addition in terms of support and maintenance after the RFC process is completed - -## Planned work - -* **Automated schema implementation**: on merge of a Proposal PR, automatically apply the proposed field definitions to the schema. -* **Automated field promotion**: automatically promote fields from beta to GA once an adoption threshold is met. From eea8cd1006e9da537999fe9b05c6e6ea619e0784 Mon Sep 17 00:00:00 2001 From: Kylie Meli Date: Wed, 8 Apr 2026 10:34:58 -0400 Subject: [PATCH 4/9] Update CHANGELOG.next.md --- CHANGELOG.next.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.next.md b/CHANGELOG.next.md index cab44d0db6..9de7f47877 100644 --- a/CHANGELOG.next.md +++ b/CHANGELOG.next.md @@ -30,6 +30,8 @@ Thanks, you're awesome :-) --> #### Improvements +* Streamline RFC process from four stages (Strawperson, Draft, Candidate, Finished) to a single Proposal stage with target maturity. #2600 + #### Deprecated ## 9.4.0 (Feature Freeze) @@ -45,4 +47,3 @@ Thanks, you're awesome :-) --> * Increase composable template `total_fields.limit` from 2000 to 2500. #2584 * Remove the `experimental/` build pipeline and unused `cgroup.*` fields; alpha and beta fields now live in `schemas/`. #2599 -* Streamline RFC process from four stages (Strawperson, Draft, Candidate, Finished) to a single Proposal stage with target maturity. #2600 From 65d1927f00b7f89ca0bfa3673ef90589018d3b9b Mon Sep 17 00:00:00 2001 From: Kylie Meli Date: Wed, 8 Apr 2026 16:28:44 -0400 Subject: [PATCH 5/9] pr feedback --- rfcs/0000-rfc-template.md | 17 ++++++++--------- rfcs/PROCESS.md | 19 +++++-------------- 2 files changed, 13 insertions(+), 23 deletions(-) diff --git a/rfcs/0000-rfc-template.md b/rfcs/0000-rfc-template.md index 0fa5e1617b..32d4217d16 100644 --- a/rfcs/0000-rfc-template.md +++ b/rfcs/0000-rfc-template.md @@ -1,5 +1,5 @@ # 0000: Name of RFC - + - Stage: **Proposal** - Date: **TBD** @@ -15,18 +15,18 @@ Remove these guidance comments as you fill out each section. Provide a high level summary of the premise of these changes. Briefly describe the nature, purpose, and impact of the changes. ~2-5 sentences. --> -## Fields +## Usage -## Usage +## Fields ## Source data @@ -60,12 +60,11 @@ The following are the people that consulted on the contents of this RFC. * TBD | author - Date: **TBD** -- Target maturity: **alpha | beta** +- Target maturity: **alpha | beta | mixture** ## Source data From 76d2c0f4dd22f5e471fcbf3ef0a5b4d24549e7b6 Mon Sep 17 00:00:00 2001 From: Kylie Meli Date: Mon, 13 Apr 2026 09:08:33 -0400 Subject: [PATCH 8/9] Update rfcs/README.md Co-authored-by: Alexandra Konrad --- rfcs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/README.md b/rfcs/README.md index 298e1d2ff1..2806975582 100644 --- a/rfcs/README.md +++ b/rfcs/README.md @@ -17,7 +17,7 @@ Check out [Proposing Changes](./PROCESS.md) for high level information about the 2. Fill in all sections of the template, including the target maturity (alpha or beta) for the proposed fields. 3. Open a PR to commit your RFC to [rfcs/](./). 4. The ECS committee reviews the proposal and provides feedback. -5. On approval the committee merges the PR, and the ECS team assigns a unique RFC number. +5. On approval the ECS team verifies a unique RFC number and merges the PR If the RFC includes field additions or modifications, create a folder named after the RFC number under [rfcs/text/](./text/). This is where proposed schema changes as standalone YAML files, extended example mappings, and larger source documents should go. From 0a3af94ae4ba23214ebe4f0ad779b207b1a3b640 Mon Sep 17 00:00:00 2001 From: Kylie Meli Date: Mon, 13 Apr 2026 09:33:38 -0400 Subject: [PATCH 9/9] promotion clarity --- rfcs/PROCESS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/PROCESS.md b/rfcs/PROCESS.md index 6e220e9781..ed9087a889 100644 --- a/rfcs/PROCESS.md +++ b/rfcs/PROCESS.md @@ -12,7 +12,7 @@ Each RFC is a markdown document following the [template](./0000-rfc-template.md) 4. On approval the ECS team merges the PR and confirms the RFC number. 5. The proposed fields are added to the schema at the accepted maturity level (by the contributor or the ECS team). This step will be automated in the future so that field definitions are applied to the schema on merge of the Proposal PR. -GA promotion is handled separately through the field lifecycle process and does not require a new RFC. In the future, fields will be automatically promoted from beta to GA once an adoption threshold is met. If a proposal is no longer being pursued, the PR is simply closed. +Field promotion is handled separately and does not require a new RFC. Fields at **alpha** maturity will be periodically reviewed; based on adoption and feedback, the ECS team will decide whether to promote them to beta or remove them. Fields at **beta** maturity will be automatically promoted to GA once an adoption threshold is met. The details of both promotion paths are still being finalized. If a proposal is no longer being pursued, the PR is simply closed. ## Key questions