You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@kie.apache.org by "wmedvede (via GitHub)" <gi...@apache.org> on 2026/04/20 13:21:11 UTC
[PR] kie-kogito-docs-757: Add a section explaining the workflow id naming and versioning recommended practices and limitations [incubator-kie-kogito-docs]
wmedvede opened a new pull request, #758:
URL: https://github.com/apache/incubator-kie-kogito-docs/pull/758
<!-- Please don't forget your Issue link -->
Closes/Fixes/Resolves #ISSUE-NUMBER
<!-- Please provide a short description of what this PR does -->
**Description:**
<!-- Link to related PRs: -->
Please make sure that your PR meets the following requirements:
- [ ] You have read the [contributions doc](https://github.com/apache/incubator-kie-kogito-docs/blob/main/CONTRIBUTING.md)
- [ ] Pull Request title is properly formatted: `Issue-XYZ Subject`
- [ ] Pull Request title contains the target branch if not targeting main: `[0.9.x] Issue-XYZ Subject`
- [ ] The nav.adoc file has a link to this guide in the proper category
- [ ] The index.adoc file has a card to this guide in the proper category, with a meaningful description
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@kie.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@kie.apache.org
For additional commands, e-mail: commits-help@kie.apache.org
Re: [PR] kie-kogito-docs-757: Add a section explaining the workflow id naming and versioning recommended practices and limitations [incubator-kie-kogito-docs]
Posted by "wmedvede (via GitHub)" <gi...@apache.org>.
wmedvede commented on PR #758:
URL: https://github.com/apache/incubator-kie-kogito-docs/pull/758#issuecomment-4281366563
closes: #757
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@kie.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@kie.apache.org
For additional commands, e-mail: commits-help@kie.apache.org
Re: [PR] kie-kogito-docs-757: Add a section explaining the workflow id naming and versioning recommended practices and limitations [incubator-kie-kogito-docs]
Posted by "wmedvede (via GitHub)" <gi...@apache.org>.
wmedvede commented on code in PR #758:
URL: https://github.com/apache/incubator-kie-kogito-docs/pull/758#discussion_r3112246158
##########
serverlessworkflow/modules/ROOT/pages/_common-content/workflow-identifier-and-version.adoc:
##########
@@ -0,0 +1,112 @@
+:page-partial:
+
+== Workflow identifiers
+
+To ensure proper functionality across all deployment variants, ranging from standalone Java workflow applications, to deployments managed by the {operator_name}, workflow identifiers must comply with RFC 1123 DNS label standards.
+
+In practice, this means that a workflow identifier must:
+
+* Contain only:
+** Lowercase letters (a–z)
+** Digits (0–9)
+** Hyphens (-)
+** Start with a lowercase letter or digit
+** End with a lowercase letter or digit
+
+Identifiers that do not meet these requirements may lead to deployment or runtime issues.
+
+The following examples demonstrate valid workflow identifiers:
+
+.Valid workflow identifiers
+[source,text]
+----
+order-processing
+invoice123
+customer-onboarding-flow
+flow-01
+----
+
+
+.Invalid workflow identifiers
+[source,text]
+----
+OrderProcessing (uppercase letters not allowed)
+order_processing (underscores not allowed)
+-orderflow (cannot start with a hyphen)
+orderflow- (cannot end with a hyphen)
+----
+
+Additionally, you must be sure that the workflow identifier is consistent across all the configurations used to build and deploy your workflow.
+This is particularly important when you work with {operator_name} driven deployments that uses the `gitops` profile.
+
+The following example shows a `yaml` workflow definition used to build a workflow image for a `gitops` profile deployment, and the corresponding `SonataFlow` CR configuration:
+
+.Example of a valid workflow `id` configuration for a yaml workflow definition
+[source,yaml]
+----
+id: hello-world <1>
+version: "1.0" <2>
+specVersion: 0.8.0 <3>
+name: Hello World <4>
+description: An example workflow to say Hello World <5>
+start: HelloWorld
+ # rest of the workflow definition omitted to shorten the example
+----
+<1> The workflow `id` must be a valid RFC 1123 DNS label name.
+<2> The workflow version.
+<3> The CNCF Serverless Workflow specification version.
+<4> Optional human-readable name.
+<5> Optional workflow description.
+
+[IMPORTANT]
+====
+Although the CNCF Serverless Workflow specification allows you to define a workflow version, and this attribute can be set in your workflow definition, the current {product_name} ecosystem does not support multiple versions of a workflow that share the same `id`.
+Be sure that you have read <<workflow_versioning, workflow version support and recommended versioning approach>>.
+====
+
+.Example of a valid workflow configuration for the `gitops` profile
+
+[source,yaml]
+----
+apiVersion: sonataflow.org/v1alpha08 <1>
+kind: SonataFlow
+metadata:
+ name: hello-world <2>
+ annotations:
+ sonataflow.org/name: Hello World <3>
+ sonataflow.org/description: An example workflow to say Hello World <4>
+ sonataflow.org/version: 1.0 <5>
+ sonataflow.org/profile: gitops
+spec:
+ podTemplate:
+ container:
+ image: "quay.io/my-workflows/hello-world:1.0"
+ flow:
+ start: HelloWorld
+ # rest of the workflow definition omitted to shorten the example
+----
+
+<1> The `SonataFlow` CR apiVersion infers the CNCF specification version. Currently, the only supported version is 0.8.0.
+<2> The `SonataFlow` CR Kubernetes `name` represents the workflow `id`, and must be configured with the same value used in the workflow `yaml` or `json` file.
+<3> Use the `sonataflow.org/name` annotation to configure the optional human-readable workflow name configured in the workflow `yaml` or `json` file if any.
+<4> Use the `sonataflow.org/description` annotation to configure the optional human-readable workflow description configured in the workflow `yaml` or `json` file if any.
+<5> The `sonataflow.org/version` annotation must be configured with the same value used as `version` in the workflow `yaml` or `json` file.
+
+[#workflow_versioning]
+== Workflow version support and recommended versioning approach
+
+Although the CNCF Serverless Workflow specification allows you to define a workflow version, and this attribute can be set in your workflow definition, the current {product_name} ecosystem does not support multiple versions of a workflow that share the same id.
Review Comment:
Since it's a kind of key information, and we have detected many users doing the same error, I preferd to repeat that paragraph, just in case an ancious user never reads the next section.
But totally agree, it's a duplication.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@kie.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@kie.apache.org
For additional commands, e-mail: commits-help@kie.apache.org
Re: [PR] kie-kogito-docs-757: Add a section explaining the workflow id naming and versioning recommended practices and limitations [incubator-kie-kogito-docs]
Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] commented on PR #758:
URL: https://github.com/apache/incubator-kie-kogito-docs/pull/758#issuecomment-4281112677
🎊 PR Preview 41040655a1ca5ce192934b2e2e103dadca72cfbf has been successfully built and deployed. See the documentation preview: https://sonataflow-docs-preview-pr-758.surge.sh
<!-- Sticky Pull Request Comment -->
<!-- Sticky Pull Request Comment -->
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@kie.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@kie.apache.org
For additional commands, e-mail: commits-help@kie.apache.org
Re: [PR] kie-kogito-docs-757: Add a section explaining the workflow id naming and versioning recommended practices and limitations [incubator-kie-kogito-docs]
Posted by "ricardozanini (via GitHub)" <gi...@apache.org>.
ricardozanini commented on code in PR #758:
URL: https://github.com/apache/incubator-kie-kogito-docs/pull/758#discussion_r3111467885
##########
serverlessworkflow/modules/ROOT/pages/_common-content/workflow-identifier-and-version.adoc:
##########
@@ -0,0 +1,112 @@
+:page-partial:
+
+== Workflow identifiers
+
+To ensure proper functionality across all deployment variants, ranging from standalone Java workflow applications, to deployments managed by the {operator_name}, workflow identifiers must comply with RFC 1123 DNS label standards.
+
+In practice, this means that a workflow identifier must:
+
+* Contain only:
+** Lowercase letters (a–z)
+** Digits (0–9)
+** Hyphens (-)
+** Start with a lowercase letter or digit
+** End with a lowercase letter or digit
+
+Identifiers that do not meet these requirements may lead to deployment or runtime issues.
+
+The following examples demonstrate valid workflow identifiers:
+
+.Valid workflow identifiers
+[source,text]
+----
+order-processing
+invoice123
+customer-onboarding-flow
+flow-01
+----
+
+
+.Invalid workflow identifiers
+[source,text]
+----
+OrderProcessing (uppercase letters not allowed)
+order_processing (underscores not allowed)
+-orderflow (cannot start with a hyphen)
+orderflow- (cannot end with a hyphen)
+----
+
+Additionally, you must be sure that the workflow identifier is consistent across all the configurations used to build and deploy your workflow.
+This is particularly important when you work with {operator_name} driven deployments that uses the `gitops` profile.
+
+The following example shows a `yaml` workflow definition used to build a workflow image for a `gitops` profile deployment, and the corresponding `SonataFlow` CR configuration:
+
+.Example of a valid workflow `id` configuration for a yaml workflow definition
+[source,yaml]
+----
+id: hello-world <1>
+version: "1.0" <2>
+specVersion: 0.8.0 <3>
+name: Hello World <4>
+description: An example workflow to say Hello World <5>
+start: HelloWorld
+ # rest of the workflow definition omitted to shorten the example
+----
+<1> The workflow `id` must be a valid RFC 1123 DNS label name.
+<2> The workflow version.
+<3> The CNCF Serverless Workflow specification version.
+<4> Optional human-readable name.
+<5> Optional workflow description.
+
+[IMPORTANT]
+====
+Although the CNCF Serverless Workflow specification allows you to define a workflow version, and this attribute can be set in your workflow definition, the current {product_name} ecosystem does not support multiple versions of a workflow that share the same `id`.
+Be sure that you have read <<workflow_versioning, workflow version support and recommended versioning approach>>.
+====
+
+.Example of a valid workflow configuration for the `gitops` profile
+
+[source,yaml]
+----
+apiVersion: sonataflow.org/v1alpha08 <1>
+kind: SonataFlow
+metadata:
+ name: hello-world <2>
+ annotations:
+ sonataflow.org/name: Hello World <3>
+ sonataflow.org/description: An example workflow to say Hello World <4>
+ sonataflow.org/version: 1.0 <5>
+ sonataflow.org/profile: gitops
+spec:
+ podTemplate:
+ container:
+ image: "quay.io/my-workflows/hello-world:1.0"
+ flow:
+ start: HelloWorld
+ # rest of the workflow definition omitted to shorten the example
+----
+
+<1> The `SonataFlow` CR apiVersion infers the CNCF specification version. Currently, the only supported version is 0.8.0.
+<2> The `SonataFlow` CR Kubernetes `name` represents the workflow `id`, and must be configured with the same value used in the workflow `yaml` or `json` file.
+<3> Use the `sonataflow.org/name` annotation to configure the optional human-readable workflow name configured in the workflow `yaml` or `json` file if any.
+<4> Use the `sonataflow.org/description` annotation to configure the optional human-readable workflow description configured in the workflow `yaml` or `json` file if any.
+<5> The `sonataflow.org/version` annotation must be configured with the same value used as `version` in the workflow `yaml` or `json` file.
+
+[#workflow_versioning]
+== Workflow version support and recommended versioning approach
+
+Although the CNCF Serverless Workflow specification allows you to define a workflow version, and this attribute can be set in your workflow definition, the current {product_name} ecosystem does not support multiple versions of a workflow that share the same id.
Review Comment:
Aren't we repeating the same info from `IMPORTANT` box? Is this necessary?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@kie.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@kie.apache.org
For additional commands, e-mail: commits-help@kie.apache.org
Re: [PR] kie-kogito-docs-757: Add a section explaining the workflow id naming and versioning recommended practices and limitations [incubator-kie-kogito-docs]
Posted by "wmedvede (via GitHub)" <gi...@apache.org>.
wmedvede merged PR #758:
URL: https://github.com/apache/incubator-kie-kogito-docs/pull/758
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@kie.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@kie.apache.org
For additional commands, e-mail: commits-help@kie.apache.org