From c2b35cb097ab3e6d1e52dc2898eec73f02af081b Mon Sep 17 00:00:00 2001 From: Matt Wynne Date: Fri, 24 Jul 2026 09:22:52 -0700 Subject: [PATCH 1/3] Add an ADR about the messagebuilder work --- adrgen.config.yml | 12 +++++++ .../adrs/0001-slim-down-the-messagebuilder.md | 33 +++++++++++++++++++ docs/adrs/adr_template.md | 19 +++++++++++ 3 files changed, 64 insertions(+) create mode 100644 adrgen.config.yml create mode 100644 docs/adrs/0001-slim-down-the-messagebuilder.md create mode 100644 docs/adrs/adr_template.md diff --git a/adrgen.config.yml b/adrgen.config.yml new file mode 100644 index 0000000000..39fcb59e3f --- /dev/null +++ b/adrgen.config.yml @@ -0,0 +1,12 @@ +default_meta: [] +default_status: proposed +directory: docs/adrs +id_digit_number: 4 +supported_statuses: + - proposed + - accepted + - rejected + - superseded + - amended + - deprecated +template_file: docs/adrs/adr_template.md diff --git a/docs/adrs/0001-slim-down-the-messagebuilder.md b/docs/adrs/0001-slim-down-the-messagebuilder.md new file mode 100644 index 0000000000..8e2a054f45 --- /dev/null +++ b/docs/adrs/0001-slim-down-the-messagebuilder.md @@ -0,0 +1,33 @@ +# 1. Slim down the MessageBuilder + +Date: 2026-07-24 + +## Status + +accepted + +## Context + +The MessageBuilder has its tentacles in everything. For example, the `Formatter::HTML` inherits from it, and needs a reasonable amount of the methods, but it's hard to see which ones. It's a big class that does way too much. + +When we introduce new formatters, we want them to work in a clean/easy way: just an `on_envelop` method, instead needing to listen to 10 different events. + +## Decision + +Remove all the other event listener methods from `MessageBuilder` so that we could eventually remove it altogether. + +In the end, we want to have only one event on the bus: `envelope`. Then we'll be able to change our event bus to just handle envelopes/messages. + +## Consequences + +* each time we remove an event listener from MessageBuilder we need to simultaneously: + * add the translated/generated event of type `envelope` next to the source of the actual event. Note: this may not be a direct 1:1 relationship between message/event. + * remove the handler from `MessageBuilder` and ensure that any new formatter (these don't have to directly inherit) is checked and refactored. + +When converting between messages and envelopes, there are three ways it could go: + +1. event <-> message +2. events that don't have a corresponding message (e.g. `gherkin_source_read`, `test_case_ready`) +3. messages that don't have a corresponding (obvious) event (e.g. `meta`) + +Each needs to be taken case-by-case. diff --git a/docs/adrs/adr_template.md b/docs/adrs/adr_template.md new file mode 100644 index 0000000000..fd5a1f796f --- /dev/null +++ b/docs/adrs/adr_template.md @@ -0,0 +1,19 @@ +# {title} + +Date: {date} + +## Status + +{status} + +## Context + +What is the issue that we're seeing that is motivating this decision or change? + +## Decision + +What is the change that we're proposing and/or doing? + +## Consequences + +What becomes easier or more difficult to do because of this change? \ No newline at end of file From abb9536cfe0b0fed07fd61e56360ce96bcbb71c9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Rasmusson?= Date: Fri, 24 Jul 2026 21:19:25 +0200 Subject: [PATCH 2/3] Focus on generating Messages at the message data source * Rather than focusing on the MessageBuilder, focus on the Messages should be generated at the message data source (and eventually replace Events completely). --- docs/adrs/0001-slim-down-the-messagebuilder.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/adrs/0001-slim-down-the-messagebuilder.md b/docs/adrs/0001-slim-down-the-messagebuilder.md index 8e2a054f45..137fde8425 100644 --- a/docs/adrs/0001-slim-down-the-messagebuilder.md +++ b/docs/adrs/0001-slim-down-the-messagebuilder.md @@ -1,4 +1,4 @@ -# 1. Slim down the MessageBuilder +# 1. Generate Messages at the source of the message data Date: 2026-07-24 @@ -8,23 +8,23 @@ accepted ## Context -The MessageBuilder has its tentacles in everything. For example, the `Formatter::HTML` inherits from it, and needs a reasonable amount of the methods, but it's hard to see which ones. It's a big class that does way too much. - -When we introduce new formatters, we want them to work in a clean/easy way: just an `on_envelop` method, instead needing to listen to 10 different events. +The several Messages are (still) generated centrally from Events by the MessageBuilder. The goal is that each Message are generated at the source of the message data (which often is where the correspondeing Event is generated). ## Decision -Remove all the other event listener methods from `MessageBuilder` so that we could eventually remove it altogether. +Generate each Messages at the source of the message data. When all the Messages are generated at the source of the message data the `MessageBuilder` could be remove it altogether. + +The next step is to convert all the Event users to use Messages instead. Many of the Event users are formatters, but there are also other Event users, for instance the Retry filter. In the end, we want to have only one event on the bus: `envelope`. Then we'll be able to change our event bus to just handle envelopes/messages. ## Consequences -* each time we remove an event listener from MessageBuilder we need to simultaneously: - * add the translated/generated event of type `envelope` next to the source of the actual event. Note: this may not be a direct 1:1 relationship between message/event. - * remove the handler from `MessageBuilder` and ensure that any new formatter (these don't have to directly inherit) is checked and refactored. +* each time we start to generate a Message at the message data source we need simulato simultaneously + * stop the MessageBuilder to generate it. Usually that also means that a handler can be removed from the MessageBuilder. Note: this may not be a direct 1:1 relationship between message/event. + * ensure that any Message user is checked. -When converting between messages and envelopes, there are three ways it could go: +When converting between event and messages, there are three ways it could go: 1. event <-> message 2. events that don't have a corresponding message (e.g. `gherkin_source_read`, `test_case_ready`) From d9ac49b071c43f46b7ab2518ce984d5a44ccd06b Mon Sep 17 00:00:00 2001 From: Luke Hill <20105237+luke-hill@users.noreply.github.com> Date: Mon, 27 Jul 2026 18:39:52 +0100 Subject: [PATCH 3/3] Styling update --- .../adrs/0001-slim-down-the-messagebuilder.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/adrs/0001-slim-down-the-messagebuilder.md b/docs/adrs/0001-slim-down-the-messagebuilder.md index 137fde8425..1b2ed8f73e 100644 --- a/docs/adrs/0001-slim-down-the-messagebuilder.md +++ b/docs/adrs/0001-slim-down-the-messagebuilder.md @@ -4,30 +4,30 @@ Date: 2026-07-24 ## Status -accepted +Accepted (Pending Review) ## Context -The several Messages are (still) generated centrally from Events by the MessageBuilder. The goal is that each Message are generated at the source of the message data (which often is where the correspondeing Event is generated). +Several Messages are (still), generated centrally from `Event`s by the `MessageBuilder` class. The goal is that each Message is generated at the source (time), of the specific message data being produced (which often is where the corresponding `Event` is generated - and published). ## Decision -Generate each Messages at the source of the message data. When all the Messages are generated at the source of the message data the `MessageBuilder` could be remove it altogether. - -The next step is to convert all the Event users to use Messages instead. Many of the Event users are formatters, but there are also other Event users, for instance the Retry filter. +Generate each `Message` at source (of the message data). When all `Message`s are generated at their source(s), of the message data; the `MessageBuilder` class can be removed altogether. In the end, we want to have only one event on the bus: `envelope`. Then we'll be able to change our event bus to just handle envelopes/messages. +Then; the next step will be to convert all the `Event` users to use `Message`s instead. Many of the `Event` users are formatters, but there are also other `Event` users, for instance the Retry filter. + ## Consequences -* each time we start to generate a Message at the message data source we need simulato simultaneously - * stop the MessageBuilder to generate it. Usually that also means that a handler can be removed from the MessageBuilder. Note: this may not be a direct 1:1 relationship between message/event. - * ensure that any Message user is checked. +* Each time we start to generate a Message at the message data source we need simultaneously... + * Stop the MessageBuilder from generating it. Usually that also means that a handler can be removed from the MessageBuilder. Note: this may not be a direct 1:1 relationship between message/event. + * Ensure that any Message user/consumer is checked. Especially if the new source location of the envelope event is outside of the main `cucumber-ruby` gem -When converting between event and messages, there are three ways it could go: +When converting between `Event`s and `Message`s, there are three ways the relationship could go: -1. event <-> message -2. events that don't have a corresponding message (e.g. `gherkin_source_read`, `test_case_ready`) -3. messages that don't have a corresponding (obvious) event (e.g. `meta`) +1. 1:1 relationship between `Event` <-> `Message` +2. `Event`s that don't have a corresponding `Message` (e.g. `gherkin_source_read`, `test_case_ready`) +3. `Message`s that don't have a corresponding (obvious) event (e.g. `meta`) Each needs to be taken case-by-case.