From 82db57b38ec82740fb420675c9d07054a318ae8f Mon Sep 17 00:00:00 2001 From: Lorna-Kelly Date: Fri, 20 Feb 2026 16:00:39 +0000 Subject: [PATCH] Add Shared CNCF Workflow Specification Editor & Multi-Maintainer Collaboration Model ADR Signed-off-by: lornakelly Signed-off-by: Dmitriy Co-authored-by: Charles d'Avernas --- adr/v1.0-adr-shared-workflow-editor.md | 194 +++++++++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 adr/v1.0-adr-shared-workflow-editor.md diff --git a/adr/v1.0-adr-shared-workflow-editor.md b/adr/v1.0-adr-shared-workflow-editor.md new file mode 100644 index 00000000..0c259ee3 --- /dev/null +++ b/adr/v1.0-adr-shared-workflow-editor.md @@ -0,0 +1,194 @@ +# ADR: Shared CNCF Workflow Specification Editor & Multi-Maintainer Collaboration Model + +## Status + +Proposed + +## Context + +There is a need for a shared editor for the CNCF Serverless 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 visualization experiences, leading to duplicated effort and fragmented tooling. + +Today we have: + +- An existing (but aging) VS Code extension for Serverless Workflow +- Several product-specific editors embedded in consoles or IDEs +- Fragmented UX and duplicated effort around: + - YAML/JSON authoring + - Visual diagramming + - Validation against the spec schema + +We want to converge on a single core editor stack driven by the CNCF +Serverless Workflow Specification, with a collaboration model that allows +multiple vendors/maintainers to contribute and embed it. + +This ADR formalizes the decision to build a shared editor, with a strictly +scoped MVP, aligned with the proposal outlined in +[serverlessworkflow/specification#1131](https://github.com/serverlessworkflow/specification/issues/1131) and further refined through MVP +scoping discussions. + +## Decision + +After evaluating existing solutions, potential approaches, and their +associated dependencies, we decided to build the editor from scratch to +retain full ownership of the architecture and release process, prioritize +architectural simplicity, enable CNCF hosting and long-term sustainability, +at the cost of slower initial delivery. + +## Licensing + +- Apache 2.0. +- All dependencies must be CNCF compatible. +- React Flow is MIT licensed and acceptable. + +## Governance & Community Alignment + +We want a multi-maintainer editor project that does not belong to a single +vendor. + +### Proposed model + +- Repository ownership + - New repo under the CNCF Serverless Workflow Specification org, e.g. `workflow-spec-editor` (name TBD). + +- Maintainers + + - Initial maintainers: representatives from at least: + - CNCF Serverless Workflow Specification maintainers + - Quarkus Flow / SonataFlow + - Other interested engine maintainers (e.g. ZigFlow / Synapse / Lemline etc.). + +- Decision process + + - Use the spec’s existing governance as a reference (PR review rules, approvals). + + - Editor decisions should: + - Respect the spec as the single source of truth + - Avoid baking in engine-specific opinions by default + +- Integration responsibilities + + - Core editor project provides: + + - NPM package(s) + - Reference VS Code extension + - Docs and examples + + - Each implementation (Quarkus Flow, Synapse, etc.) owns: + + - Their integration/embedding + - Optional extension/profile configuration + +- Release strategy + - Align with spec releases when possible (e.g. new spec fields -> new editor release). + - Support at least the latest minor and one previous minor version of the spec. + +## Initial Scope (v1.0) + +### 1. In Scope + +- Read-only visual representation of YAML / JSON workflow definitions +- Visualize all task types and transitions +- Fully expanded nested task visualization +- Indication of basic validation issues +- Editor available via NPM package +- A simple demo app showing how to embed the editor as a component +- Documentation for integrators + +### 2. UX & Design Decisions + +- Light and dark theme support +- Localization infrastructure in place, English only content for MVP +- Rely on out-of-the-box accessibility from React Flow +- Responsiveness is not a focus for MVP, as the editor is intended for + desktop usage rather than mobile devices + +### 3. Diagram Semantics & Representation + +- Support all task types defined by the Serverless Workflow specification. +- Twelve task types represented visually. +- Task types differentiated using icons, custom node shapes are avoided for MVP due to layout complexity. + +### 4. Validation + +- The editor performs lightweight client-side schema/structural validation to determine whether the workflow can be rendered. +- The backend (runtime implementation) remains the source of truth for full specification conformance and advanced validation rules. + - 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. +- 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. + +### 5. Nested Tasks & Layout Strategy + +- All nested tasks are fully expanded in the diagram. +- No collapsing or layered presentation in MVP. Collapsible or hierarchical views are deferred due to layout and UX complexity. +- Nested workflow UX will be revisited post MVP. + +### 6. Development & Tooling Decisions Overview (MVP) + +- Web-based implementation +- React/TypeScript-based architecture +- Diagram rendering via React Flow +- Webpack for application bundling +- Jest for unit testing +- Playwright for end-to-end testing +- Storybook for component development and documentation +- Node.js for development and build tooling +- pnpm for dependency management +- GitHub Dependabot for dependency security and updates + +## Consequences + +### Positive + +- CNCF-aligned ownership +- Lowers the entry barrier to the CNCF Serverless Workflow Specification +- Encourages understanding and usage of workflow semantics +- Reduces duplicated tooling effort across runtimes +- Provides a shared, consistent user experience +- Enables incremental evolution without over-engineering MVP +- Clear architectural simplicity and long-term maintainability +- Full control over release cadence and scope + +### Trade-Offs + +- Slower initial feature delivery compared to reuse-based approaches +- Temporary feature gap relative to existing editors, as the initial scope + must remain conservative while the editor is built from the ground up +- Increased upfront engineering investment +- Limited UX sophistication in MVP +- Requires ongoing coordination to keep the editor aligned with evolving + specification versions + +## Milestones + +### Milestone 1 (August 2026) - MVP Editor + +- Editor available via NPM package +- Read-only visual representation of workflows +- Light/dark theme support +- English only locale setup +- Basic error feedback when rendering fails +- Demo web app + +### Milestone 2 (December 2026) - Dual Visual/Text Editor for YAML/JSON workflows + +- Dual visual and text editor +- Text and visual toggles +- The editor should be able to write back to disk, and users should be able + to have complete freedom to create, update, and delete nodes - including + creating a new workflow from the ground up +- Syntax highlighting and validation +- VS Code and Chrome extensions + +### Milestone 3 (TBD/2027) - External Catalogs and Messaging Support + +- Add every OpenAPI spec available in the context to ease creation of + OpenAPI-based tasks +- Connect to external catalogs such as Apicurio (others to evaluate and + explore at the time) to ease creation of OpenAPI and HTTP-based tasks +- Interfaces to start workflows with CloudEvents – support for events data + structure (pluggable via HTTP to connect to any backend) +- Mock services from the OpenAPI catalog, so users won't need to have all the + services available to test their workflows while editing