docs: Add release please flow and config information

docs/Release-Workflow.md

@@ -0,0 +1,131 @@
+# Release Please Workflow
+
+This document explains the automated release and publishing workflow for the UI5 CLI monorepo using [Release Please](https://github.com/googleapis/release-please).
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Workflow Architecture](#workflow-architecture)
+- [Release Please Configuration](#release-please-configuration)
+
+## Overview
+
+UI5 CLI uses an automated release workflow powered by Release Please to perform the following tasks:
+1. **Automatically generate release PRs** based on Conventional Commits
+2. **Update version numbers** across all workspace packages synchronously
+3. **Generate changelogs** for each package
+4. **Publish packages to npm** sequentially to respect dependency order
+5. **Create GitHub releases** with release notes
+
+## Workflow Architecture
+
+![Release Workflow Diagram](./release-workflow-diagram.svg)
+
+The workflow consists of three main jobs:
+
+### 1. `release-please` Job
+- **Trigger**: Push to `main` branch
+- **Purpose**: Creates/updates version bumps and changelogs for all of the packages in a single PR.
+
+### 2. `publish-packages` Job
+- **Trigger**: Merge of release PR into `main` branch
+- **Action**: Developer merges the release PR in GitHub
+- **Result**: 
+  - Release Please creates separate releases & tags in GitHub for every package
+  - Packages are published to NPM sequentially (logger → fs → builder → server → project)
+- **Strategy**: Sequential execution (`max-parallel: 1`) to ensure dependencies exist before dependents
+
+### 3. `publish-cli` Job
+- **Trigger**: All other packages have been published
+- **Purpose**: Generates `npm-shrinkwrap.json` using `shrinkwrap-extractor` and publishes the CLI package
+- **Why separate**: The shrinkwrap must contain published registry versions of workspace packages, not workspace links. This requires all dependencies to be available on npm registry first.
+- **How it works**: The `shrinkwrap-extractor` reads the monorepo's `package-lock.json`, extracts production dependencies for `@ui5/cli`, converts workspace references to registry URLs, and generates a valid `npm-shrinkwrap.json` that will be included in the published CLI package.
+
+## Release Please Configuration
+
+The configuration is defined in [`release-please-config.json`](../release-please-config.json). This section explains our specific configuration choices and constraints.
+
+### Key Configuration Decisions
+
+#### PR Title Pattern
+
+```json
+"group-pull-request-title-pattern": "release: UI5 CLI packages ${branch}"
+```
+
+**Why we can't use `${version}`**: When using the `linked-versions` plugin, Release Please doesn't support the `${version}` placeholder in the PR title pattern when creating single PR with multiple packages. In such case release please does not have a single source of truth even though packages are released under the same version. 
+Adding the root package, will resolve this, but it will pollute the release notes with unnecessary information that we need to manually remove.
+
+**Documentation**: [group-pull-request-title-pattern](https://github.com/googleapis/release-please?tab=readme-ov-file#group-pull-request-title-pattern)
+
+---
+
+#### Prerelease Configuration
+
+```json
+"prerelease": true,
+"prerelease-type": "alpha",
+"release-as": "5.0.0-alpha.0"
+```
+
+**Purpose**: We're currently in alpha phase for v5.0.0. Once stable, these flags should be removed to enable normal semantic versioning.
+
+---
+
+#### Package Configuration
+
+```json
+"packages": {
+  "packages/logger": { "component": "logger" },
+  "packages/cli": { 
+    "component": "cli"
+  }
+}
+```
+
+**Why explicit package configuration**: We explicitly list packages rather than using `exclude-paths` to:
+1. Make it clear which packages are released
+2. Prevent accidental inclusion of internal tooling
+3. Keep the configuration maintainable
+
+**Why `"component"` doesn't include `@ui5` scope**: Using scoped names (e.g., `"@ui5/logger"`) in the component field can cause incorrect GitHub tagging behavior.
+
+
+---
+
+#### Plugin Configuration
+
+**`node-workspace` with `merge: false`**: When using `linked-versions`, the `node-workspace` plugin **must** set `merge: false` ([documented requirement](https://github.com/googleapis/release-please/blob/main/docs/manifest-releaser.md#linked-versions)). This prevents conflicts in Release Please's internal manifest processing between:
+1. The `linked-versions` plugin synchronizing versions across all packages
+2. The `node-workspace` plugin updating workspace dependency references
+
+Without this flag, Release Please may fail to generate the release PR or produce incorrect version updates.
+
+**Note**: Release Please always force-pushes to the PR branch, so this flag only affects internal manifest processing, not Git commit structure.
+
+**`linked-versions`**: All UI5 CLI packages will be released together with synchronized version numbers.
+
+**Known limitations**:
+- Cannot resolve circular peer dependencies (e.g., `@ui5/project` ↔ `@ui5/builder`)
+- May update lockfile entries for npm aliases incorrectly
+
+**Workaround**: We manually update circular peer dependencies in the workflow after Release Please runs.
+
+---
+
+#### Changelog Sections
+
+```json
+"changelog-sections": [
+  { "type": "feat", "section": "Features" },
+  { "type": "fix", "section": "Bug Fixes" },
+  { "type": "docs", "section": "Documentation", "hidden": true }
+]
+```
+
+**Visible in changelogs**: Features, bug fixes, performance improvements, dependencies, reverts
+
+**Hidden but tracked**: Documentation, styles, refactoring, tests, build, CI, release
+
+**Rationale**: Internal changes don't need to appear in user-facing changelogs, but should still be tracked in commit history.
+

docs/release-workflow-diagram.drawio

@@ -0,0 +1,91 @@
+<mxfile host="65bd71144e">
+    <diagram name="Release Workflow" id="release-workflow">
+        <mxGraphModel dx="584" dy="1267" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1100" pageHeight="900" math="0" shadow="0">
+            <root>
+                <mxCell id="0"/>
+                <mxCell id="1" parent="0"/>
+                <mxCell id="trigger" value="Push to main&lt;br&gt;branch" style="ellipse;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;strokeWidth=2;fontStyle=1" parent="1" vertex="1">
+                    <mxGeometry x="460" y="-10" width="120" height="60" as="geometry"/>
+                </mxCell>
+                <mxCell id="arrow1" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=classic;endFill=1;" parent="1" source="trigger" target="job1" edge="1">
+                    <mxGeometry relative="1" as="geometry"/>
+                </mxCell>
+                <mxCell id="job1" value="Job 1: release-please" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=2;verticalAlign=top;fontStyle=1;fontSize=14;arcSize=10;" parent="1" vertex="1">
+                    <mxGeometry x="340" y="90" width="360" height="230" as="geometry"/>
+                </mxCell>
+                <mxCell id="job1-step1" value="• Analyzes commits since last release" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#e1f5fe;strokeColor=#01579b;align=left;spacingLeft=10;fontSize=10;" parent="1" vertex="1">
+                    <mxGeometry x="355" y="120" width="330" height="28" as="geometry"/>
+                </mxCell>
+                <mxCell id="job1-step2" value="• Creates/updates release a single PR with version bumps for each package" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#e1f5fe;strokeColor=#01579b;align=left;spacingLeft=10;fontSize=10;" parent="1" vertex="1">
+                    <mxGeometry x="355" y="163" width="330" height="28" as="geometry"/>
+                </mxCell>
+                <mxCell id="job1-step3" value="• Generates changelogs for each package" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#e1f5fe;strokeColor=#01579b;align=left;spacingLeft=10;fontSize=10;" parent="1" vertex="1">
+                    <mxGeometry x="355" y="240" width="330" height="28" as="geometry"/>
+                </mxCell>
+                <mxCell id="job1-step4" value="• Fixes circular peer dependency issues (not handled by Release Please)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#e1f5fe;strokeColor=#01579b;align=left;spacingLeft=10;fontSize=10;" parent="1" vertex="1">
+                    <mxGeometry x="355" y="279" width="330" height="28" as="geometry"/>
+                </mxCell>
+                <mxCell id="arrow2" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=classic;endFill=1;" parent="1" source="job1" target="merge-event" edge="1">
+                    <mxGeometry relative="1" as="geometry"/>
+                </mxCell>
+                <mxCell id="merge-event" value="👤 Developer&lt;br&gt;merges release PR" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;strokeWidth=2;fontStyle=1;arcSize=20;" parent="1" vertex="1">
+                    <mxGeometry x="440" y="350" width="160" height="60" as="geometry"/>
+                </mxCell>
+                <mxCell id="arrow3" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=classic;endFill=1;" parent="1" source="merge-event" target="info-box" edge="1">
+                    <mxGeometry relative="1" as="geometry"/>
+                </mxCell>
+                <mxCell id="info-box" value="✓ Release Please creates GitHub releases &amp;amp; tags for each package separately&lt;br&gt;✓ Workflow triggers package publishing" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff9e6;strokeColor=#d6b656;strokeWidth=2;fontStyle=1;fontSize=10;" parent="1" vertex="1">
+                    <mxGeometry x="355" y="440" width="330" height="45" as="geometry"/>
+                </mxCell>
+                <mxCell id="arrow4" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=classic;endFill=1;" parent="1" source="info-box" target="job2" edge="1">
+                    <mxGeometry relative="1" as="geometry"/>
+                </mxCell>
+                <mxCell id="job2" value="Job 2: publish-packages (Matrix Strategy)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;strokeWidth=2;verticalAlign=top;fontStyle=1;fontSize=14;arcSize=10;" parent="1" vertex="1">
+                    <mxGeometry x="340" y="520" width="360" height="210" as="geometry"/>
+                </mxCell>
+                <mxCell id="job2-note" value="max-parallel: 1 (Sequential Execution)" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#ffcc99;strokeColor=none;fontSize=10;fontStyle=2;" parent="1" vertex="1">
+                    <mxGeometry x="360" y="548" width="320" height="20" as="geometry"/>
+                </mxCell>
+                <mxCell id="job2-step1" value="1. Publish @ui5/logger" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#666666;align=left;spacingLeft=10;fontSize=11;" parent="1" vertex="1">
+                    <mxGeometry x="360" y="573" width="320" height="25" as="geometry"/>
+                </mxCell>
+                <mxCell id="job2-step2" value="2. Publish @ui5/fs (depends on logger)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#666666;align=left;spacingLeft=10;fontSize=11;" parent="1" vertex="1">
+                    <mxGeometry x="360" y="603" width="320" height="25" as="geometry"/>
+                </mxCell>
+                <mxCell id="job2-step3" value="3. Publish @ui5/builder (depends on fs, logger)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#666666;align=left;spacingLeft=10;fontSize=11;" parent="1" vertex="1">
+                    <mxGeometry x="360" y="633" width="320" height="25" as="geometry"/>
+                </mxCell>
+                <mxCell id="job2-step4" value="4. Publish @ui5/server (depends on builder, fs, logger)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#666666;align=left;spacingLeft=10;fontSize=11;" parent="1" vertex="1">
+                    <mxGeometry x="360" y="663" width="320" height="25" as="geometry"/>
+                </mxCell>
+                <mxCell id="job2-step5" value="5. Publish @ui5/project (depends on fs, logger; peer dependency to&amp;nbsp;&lt;span style=&quot;color: rgb(0, 0, 0);&quot;&gt;builder&lt;/span&gt;)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#666666;align=left;spacingLeft=10;fontSize=11;" parent="1" vertex="1">
+                    <mxGeometry x="360" y="693" width="320" height="25" as="geometry"/>
+                </mxCell>
+                <mxCell id="arrow5" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=classic;endFill=1;" parent="1" source="job2" target="job3" edge="1">
+                    <mxGeometry relative="1" as="geometry"/>
+                </mxCell>
+                <mxCell id="job3" value="Job 3: publish-cli" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;strokeWidth=2;verticalAlign=top;fontStyle=1;fontSize=14;arcSize=10;" parent="1" vertex="1">
+                    <mxGeometry x="340" y="760" width="360" height="130" as="geometry"/>
+                </mxCell>
+                <mxCell id="job3-step1" value="1. Generate npm-shrinkwrap.json" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#666666;align=left;spacingLeft=10;fontSize=11;" parent="1" vertex="1">
+                    <mxGeometry x="360" y="790" width="320" height="25" as="geometry"/>
+                </mxCell>
+                <mxCell id="job3-step2" value="2. Publish @ui5/cli with shrinkwrap" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#666666;align=left;spacingLeft=10;fontSize=11;" parent="1" vertex="1">
+                    <mxGeometry x="360" y="820" width="320" height="25" as="geometry"/>
+                </mxCell>
+                <mxCell id="job3-complete" value="✓ All packages published to npm" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#b1ddf0;strokeColor=#10739e;fontStyle=1;fontSize=11;" parent="1" vertex="1">
+                    <mxGeometry x="360" y="850" width="320" height="25" as="geometry"/>
+                </mxCell>
+                <mxCell id="note-sequential" value="&lt;b&gt;Why sequential publishing?&lt;/b&gt;&lt;br&gt;• Packages have dependencies on each other&lt;br&gt;• NPM must have dependencies available&lt;br&gt;&amp;nbsp;&amp;nbsp;before publishing dependents&lt;br&gt;• `max-parallel: 1` ensures proper ordering" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff9e6;strokeColor=#d6b656;dashed=1;dashPattern=3 3;align=left;spacingLeft=10;fontSize=10;" parent="1" vertex="1">
+                    <mxGeometry x="740" y="580" width="280" height="100" as="geometry"/>
+                </mxCell>
+                <mxCell id="note-cli" value="&lt;b&gt;Why CLI published last?&lt;/b&gt;&lt;br&gt;• Shrinkwrap needs all dependencies (@ui5/* packages)&lt;br&gt;&amp;nbsp;&amp;nbsp;to exist on npm registry" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff9e6;strokeColor=#d6b656;dashed=1;dashPattern=3 3;align=left;spacingLeft=10;fontSize=10;" parent="1" vertex="1">
+                    <mxGeometry x="20" y="780" width="280" height="80" as="geometry"/>
+                </mxCell>
+                <mxCell id="2" value="• Synchronizes package.json intra-dependency versions for the packages" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#e1f5fe;strokeColor=#01579b;align=left;spacingLeft=10;fontSize=10;" parent="1" vertex="1">
+                    <mxGeometry x="355" y="200" width="330" height="28" as="geometry"/>
+                </mxCell>
+            </root>
+        </mxGraphModel>
+    </diagram>
+</mxfile>

release-please-config.json

@@ -21,10 +21,7 @@
 			"component": "project"
 		},
 		"packages/cli": {
-			"component": "cli",
-			"extra-files": [
-				"npm-shrinkwrap.json"
-			]
+			"component": "cli"
 		}
 	},
 	"release-type": "node",