OOTB PDLC Happy Path documentation

[christinaausley]

Description

Document the OOTB PDLC, as per the following acceptance criteria/requirements from https://github.com/camunda/product-hub/issues/2355.

Note: Getting Started Guide work may be moved into a new PR to avoid blocking the rest of the PR content from release.

Closes https://github.com/camunda/web-modeler/issues/10299, closes https://github.com/camunda/web-modeler/issues/10092)

Note: Two new issues created as result of this PR:

• Document Deploy and Play for process applications #4182
• Update "Get started with human task orchestration" guide with Play #4183

CI/CD page

• Introduce the concept of OOTB vs integrated PDLCs
  • Explain the value of an OOTB PDLC (see "release notes" section above)
  • Explain the use cases for OOTB PDLCs vs integrated PDLC
  • OOTB is appropriate for low-risk processes where you need to move fast without investing engineering effort
  • Integrated PDLC is appropriate for business-critical processes where you have strict governance or quality requirements
• There should be 2 branches in the diagram- one OOTB that stays within the modeler and one integrated that hands off to the customer's tool in their version control system
  TW: Not needed now that we have the diagram for the OOTB pipeline?
• Explain that process applications are the best solution for projects with CI/CD. Visual diffing and Git Sync (https://github.com/camunda/product-hub/issues/2036) are a powerful combination

Process applications

• Work the changes into the Idea and Purpose section
• Explain the entire journey for process application development: creation, Play, versioning+diffing+review, and promotion
  • During creation, you choose which dev cluster to use. This is persisted, removing the complexity from the deployment screen
  • Token simulation is useful during the design phase to get the process flow right
  • Play is useful for validating the behavior of the process once implementation details have been added. It's a faster, more flexible alternative to the "Deploy" or "Run" modal that's designed for the development phase
  • Versioning helps users track changes across multiple assets. You can then review the diff between two versions of a BPMN file in a visual editor. Other files can be reviewed in a Git-like code editor. Once done reviewing, it's best to create a comment in the main diagram
  • An admin should set the stages within the Modeler
  • Users can see when the process was last deployed to a particular stage This will be tackled later with https://github.com/camunda/web-modeler/issues/10231
  • When a deployment occurs, there's a comment that tracks who deployed which version to which stage.
• * Describe how processes are governed
  • This iteration focuses on establishing the process and logging activities so admins can audit process activities
  • Change Control: Users can announce a review is complete by making a comment
  • Deployment Control: Deployments can only go to pre-set approved clusters. Only users with the right privileges can deploy, and only org admins can deploy to prod-tagged clusters. Each deployment action is logged with the user and stage it was deployed to
• Describe the limitations
  • Play is not yet GA and may not be visible in their deployment. It also has its own set of limitations
  • Once created, a process app version may not be changed. Specifically, they cannot be deleted or rolled back
  • Visual diffing is not yet supported for DMN, form, connector, or other filetypes
  • Commenting is not yet supported in the milestone view. Any comments about feedback, approval, or changes required must go through the main file view
  • Governance is not yet enforceable, and comments can be deleted.
  • Defining the cluster stages, identifying clusters by tags, or promoting them are not yet supported in Self-Managed

Milestones

• Mention that process apps can simplify this flow

Getting started guides

• Play, milestone creation, and review are steps before running it on the cluster
  OUTSTANDING: requires more work & investigation, possibly move to another PR?

When should this change go live?

• This is a bug fix, security concern, or something that needs urgent release support.
• This is already available but undocumented and should be released within a week.
• This on a specific schedule and the assignee will coordinate a release with the DevEx team. (apply hold label or convert to draft PR)
• This is part of a scheduled alpha or minor. (apply alpha or minor label)
• There is no urgency with this change and can be released at any time.

PR Checklist

• My changes are for an already released minor and are in /versioned_docs directory.
• My changes are for the next minor and are in /docs directory (aka /next/).

• My changes require an Engineering review, and I've assigned the Engineering DRI or delegate.
• My changes require a technical writer review, and I've assigned @camunda/tech-writers as a reviewer.

[github-actions]

👋 🤖 🤔 Hello! Did you make your changes in all the right places?

These files were changed only in docs/. You might want to duplicate these changes in versioned_docs/version-8.5/.

• docs/components/modeler/web-modeler/create-a-process-application.md
• docs/components/modeler/web-modeler/deploy-process-application.md
• docs/components/modeler/web-modeler/img/process-applications/define-stages-deploy.png
• docs/components/modeler/web-modeler/img/process-applications/define-stages.png
• docs/components/modeler/web-modeler/img/process-applications/diagram-process-application-get-started.png
• docs/components/modeler/web-modeler/img/process-applications/diagram-process-application-pipeline.png
• docs/components/modeler/web-modeler/process-application-pipeline.md
• docs/components/modeler/web-modeler/process-application-versioning.md
• docs/components/modeler/web-modeler/process-applications.md
• docs/guides/devops-lifecycle/integrate-web-modeler-in-ci-cd.md

You may have done this intentionally, but we wanted to point it out in case you didn't. You can read more about the versioning within our docs in our documentation guidelines.

[christinaausley]

Unassigning myself -- let me know how I can help and review 👍

[mesellings]

No review as reassigned

[mesellings]

@HanselIdes @vpellegrino I have completed the first draft of the docs for the OOTB PDLC as follows:

Please review the new Process application docs that incorporate the pipeline work. I have split this into more appropriate pages, to chunk the content and make it easier for users to browse and be directed to.

For easier review, you can preview the docs at:

https://preview.docs.camunda.cloud/pr-4144/docs/next/components/modeler/web-modeler/process-applications/

Please suggest any other reviewers you feel might be helpful/appropriate?

Note: The Getting Started Guide updates will need more work and investigation, setup etc, and in the interests of time I wanted to get the main pipeline documentation out for review as I am away August 26-30. It may be that we take the Getting Started Guide work out into a new issue/PR?

[HanselIdes]

LGTM

[mesellings]

@christinaausley If you have time to take a look over the docs that would be great, but it is quite a big PR so i understand if you don't have time atm? On a side note, as you are still the PR owner I can't assign you for review, and I don't want to close the PR and lose the thread of comments etc, are you okay to just add comments or send me comments in Slack? Unless you have any other ideas of the best way to do the review - I guess this might have occurred before here?

[christinaausley]

@mesellings Feel free to approve and merge this when you're ready 👍 It has my approval!

[mesellings]

Self-approved required after approval from Christina and Eric while in draft mode (took over PR from Christina).

[github-actions]

🧹 Preview environment for this PR has been torn down.