Add ADR for Shared CNCF Workflow Specification Editor#1144
Add ADR for Shared CNCF Workflow Specification Editor#1144lornakelly wants to merge 1 commit intoserverlessworkflow:mainfrom
Conversation
…aboration Model ADR Signed-off-by: Lorna-Kelly <lorna.kelly@ibm.com>
lornakelly
force-pushed
the
adr-shared-editor
branch
from
7aa3eae to
ed5988e
Compare
There was a problem hiding this comment.
Pull request overview
Adds an Architecture Decision Record (ADR) documenting the proposal for a shared, spec-driven CNCF Workflow Specification editor and a multi-maintainer collaboration/governance model (per issue #1131).
Changes:
- Introduces an
adr/directory and adds an initial ADR for the shared editor initiative. - Documents governance/ownership, MVP scope, tooling choices, and anticipated milestones for delivery.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - Initial maintainers: representatives from at least: | ||
| - CNCF Workflow Spec maintainers | ||
| - Quarkus Flow / SonataFlow | ||
| - Other interested engine maintainers (e.g. Zigflow / Synapse / Lemline etc.). | ||
|
|
There was a problem hiding this comment.
"Zigflow" is also used here; consider updating to "ZigFlow" (matching the linked issue text) for consistent naming across the ADR.
|
|
||
| There is a need for a shared editor for the CNCF Workflow Specification that | ||
| can be used consistently by multiple implementations (e.g. Quarkus Flow, | ||
| SonataFlow, Zigflow, Synapse, Lemline), as different tools provide inconsistent |
There was a problem hiding this comment.
"Zigflow" is capitalized differently than the project name used in the linked issue text ("ZigFlow"). Consider updating capitalization for consistency and easier recognition/searchability.
| SonataFlow, Zigflow, Synapse, Lemline), as different tools provide inconsistent | |
| SonataFlow, ZigFlow, Synapse, Lemline), as different tools provide inconsistent |
| - The editor assumes workflows provided by the backend are valid. | ||
| - Edge cases to handle: validation discrepancies between the TypeScript SDK and the backend (runtime implementation). | ||
| - If rendering is possible, display warnings as needed. | ||
| - If rendering is not possible, provide clear error feedback to user. |
There was a problem hiding this comment.
The ADR lists "Indication of basic validation issues" as in-scope, but this section says the editor assumes workflows from the backend are valid. Please clarify whether the editor does any client-side schema/structural validation (even if only to support rendering) versus only surfacing backend-provided validation results.
| - The editor assumes workflows provided by the backend are valid. | |
| - Edge cases to handle: validation discrepancies between the TypeScript SDK and the backend (runtime implementation). | |
| - If rendering is possible, display warnings as needed. | |
| - If rendering is not possible, provide clear error feedback to user. | |
| - The editor performs lightweight client-side schema/structural validation required to: | |
| - Determine whether the workflow can be rendered. | |
| - Surface basic validation issues (e.g. missing required fields, unsupported task types, malformed transitions) directly in the editor. | |
| - The backend (runtime implementation) remains the source of truth for full specification conformance and advanced validation rules. | |
| - The editor surfaces backend-provided validation results alongside any client-side findings when such results are available. | |
| - Edge cases to handle: validation discrepancies between the TypeScript SDK and the backend (runtime implementation). | |
| - If structural validation passes and rendering is possible, render the workflow and display validation issues as warnings/errors in context. | |
| - If structural validation fails and rendering is not possible, do not attempt to render a partial/invalid diagram; provide clear, actionable error feedback to the user instead. |
| - Enables incremental evolution without over engineering MVP | ||
| - Clear architectural simplicity and long term maintainability |
There was a problem hiding this comment.
Hyphenation is inconsistent in a few places (e.g., "over engineering" -> "over-engineering", "long term" -> "long-term"). Consider updating these to improve readability and consistency.
| - Enables incremental evolution without over engineering MVP | |
| - Clear architectural simplicity and long term maintainability | |
| - Enables incremental evolution without over-engineering MVP | |
| - Clear architectural simplicity and long-term maintainability |
| - Read-only visual representation of YAML / JSON workflow definitions | ||
| - Visualise all task types and transitions | ||
| - Fully expanded nested task visualisation | ||
| - Indication of basic validation issues |
There was a problem hiding this comment.
This section also uses British spelling ("Visualise"/"visualisation"). If the repo standard is American English ("visualization" elsewhere), consider switching to "Visualize"/"visualization" for consistency.
| There is a need for a shared editor for the CNCF Workflow Specification that | ||
| can be used consistently by multiple implementations (e.g. Quarkus Flow, | ||
| SonataFlow, Zigflow, Synapse, Lemline), as different tools provide inconsistent | ||
| authoring and visualisation experiences, leading to duplicated effort and fragmented tooling. |
There was a problem hiding this comment.
The document uses British spelling ("visualisation"/"Visualise") but the rest of the repo appears to use American spelling (e.g., "visualization" in comparison.md). Consider standardizing to "visualization"/"Visualize" for consistency across docs.
| ### 2. UX & Design Decisions | ||
|
|
||
| - Light and dark theme support | ||
| - Localisation infrastructure in place, English only content for MVP |
There was a problem hiding this comment.
"Localisation" is British spelling; if docs in this repo are standardized on American English (e.g., "visualization" elsewhere), consider changing to "Localization" for consistency.
| - Localisation infrastructure in place, English only content for MVP | |
| - Localization infrastructure in place, English only content for MVP |
cdavernas
left a comment
cdavernas
left a comment
There was a problem hiding this comment.
Aside from Copilot's nitpicks, LGTM! Thanks ❤️
2 participants
Please specify parts of this PR update:
Discussion or Issue link:
Closes #1131
What this PR does:
Create folder for ADRs and add the proposed ADR for a Shared CNCF Workflow Specification Editor & Multi-Maintainer Collaboration Model