Skip to content

Commit 46caf3b

Browse files
d3xter666KlattG
d3xter666
and
KlattG
authored
docs: Add release please flow and config information (#1217)
JIRA: CPOUI5FOUNDATION-1166 Describes the release please workflow: #1215 Rendered document: https://github.com/UI5/cli/blob/31b5215547eeedef57bf5593d02e8fafd5a07d58/docs/Release-Workflow.md --------- Co-authored-by: Günter Klatt <[email protected]>
1 parent f640314 commit 46caf3b

File tree

4 files changed

+224
-4
lines changed

4 files changed

+224
-4
lines changed

‎docs/Release-Workflow.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Release Please Workflow
2+
3+
This document explains the automated release and publishing workflow for the UI5 CLI monorepo using [Release Please](https://github.com/googleapis/release-please).
4+
5+
## Table of Contents
6+
7+
- [Overview](#overview)
8+
- [Workflow Architecture](#workflow-architecture)
9+
- [Release Please Configuration](#release-please-configuration)
10+
11+
## Overview
12+
13+
UI5 CLI uses an automated release workflow powered by Release Please to perform the following tasks:
14+
1. **Automatically generate release PRs** based on Conventional Commits
15+
2. **Update version numbers** across all workspace packages synchronously
16+
3. **Generate changelogs** for each package
17+
4. **Publish packages to npm** sequentially to respect dependency order
18+
5. **Create GitHub releases** with release notes
19+
20+
## Workflow Architecture
21+
22+
![Release Workflow Diagram](./release-workflow-diagram.svg)
23+
24+
The workflow consists of three main jobs:
25+
26+
### 1. `release-please` Job
27+
- **Trigger**: Push to `main` branch
28+
- **Purpose**: Creates/updates version bumps and changelogs for all of the packages in a single PR.
29+
30+
### 2. `publish-packages` Job
31+
- **Trigger**: Merge of release PR into `main` branch
32+
- **Action**: Developer merges the release PR in GitHub
33+
- **Result**:
34+
- Release Please creates separate releases & tags in GitHub for every package
35+
- Packages are published to NPM sequentially (logger → fs → builder → server → project)
36+
- **Strategy**: Sequential execution (`max-parallel: 1`) to ensure dependencies exist before dependents
37+
38+
### 3. `publish-cli` Job
39+
- **Trigger**: All other packages have been published
40+
- **Purpose**: Generates `npm-shrinkwrap.json` using `shrinkwrap-extractor` and publishes the CLI package
41+
- **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.
42+
- **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.
43+
44+
## Release Please Configuration
45+
46+
The configuration is defined in [`release-please-config.json`](../release-please-config.json). This section explains our specific configuration choices and constraints.
47+
48+
### Key Configuration Decisions
49+
50+
#### PR Title Pattern
51+
52+
```json
53+
"group-pull-request-title-pattern": "release: UI5 CLI packages ${branch}"
54+
```
55+
56+
**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.
57+
Adding the root package, will resolve this, but it will pollute the release notes with unnecessary information that we need to manually remove.
58+
59+
**Documentation**: [group-pull-request-title-pattern](https://github.com/googleapis/release-please?tab=readme-ov-file#group-pull-request-title-pattern)
60+
61+
---
62+
63+
#### Prerelease Configuration
64+
65+
```json
66+
"prerelease": true,
67+
"prerelease-type": "alpha",
68+
"release-as": "5.0.0-alpha.0"
69+
```
70+
71+
**Purpose**: We're currently in alpha phase for v5.0.0. Once stable, these flags should be removed to enable normal semantic versioning.
72+
73+
---
74+
75+
#### Package Configuration
76+
77+
```json
78+
"packages": {
79+
"packages/logger": { "component": "logger" },
80+
"packages/cli": {
81+
"component": "cli"
82+
}
83+
}
84+
```
85+
86+
**Why explicit package configuration**: We explicitly list packages rather than using `exclude-paths` to:
87+
1. Make it clear which packages are released
88+
2. Prevent accidental inclusion of internal tooling
89+
3. Keep the configuration maintainable
90+
91+
**Why `"component"` doesn't include `@ui5` scope**: Using scoped names (e.g., `"@ui5/logger"`) in the component field can cause incorrect GitHub tagging behavior.
92+
93+
94+
---
95+
96+
#### Plugin Configuration
97+
98+
**`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:
99+
1. The `linked-versions` plugin synchronizing versions across all packages
100+
2. The `node-workspace` plugin updating workspace dependency references
101+
102+
Without this flag, Release Please may fail to generate the release PR or produce incorrect version updates.
103+
104+
**Note**: Release Please always force-pushes to the PR branch, so this flag only affects internal manifest processing, not Git commit structure.
105+
106+
**`linked-versions`**: All UI5 CLI packages will be released together with synchronized version numbers.
107+
108+
**Known limitations**:
109+
- Cannot resolve circular peer dependencies (e.g., `@ui5/project` ↔ `@ui5/builder`)
110+
- May update lockfile entries for npm aliases incorrectly
111+
112+
**Workaround**: We manually update circular peer dependencies in the workflow after Release Please runs.
113+
114+
---
115+
116+
#### Changelog Sections
117+
118+
```json
119+
"changelog-sections": [
120+
{ "type": "feat", "section": "Features" },
121+
{ "type": "fix", "section": "Bug Fixes" },
122+
{ "type": "docs", "section": "Documentation", "hidden": true }
123+
]
124+
```
125+
126+
**Visible in changelogs**: Features, bug fixes, performance improvements, dependencies, reverts
127+
128+
**Hidden but tracked**: Documentation, styles, refactoring, tests, build, CI, release
129+
130+
**Rationale**: Internal changes don't need to appear in user-facing changelogs, but should still be tracked in commit history.
131+

‎docs/release-workflow-diagram.drawio‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
<mxfile host="65bd71144e">
2+
<diagram name="Release Workflow" id="release-workflow">
3+
<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">
4+
<root>
5+
<mxCell id="0"/>
6+
<mxCell id="1" parent="0"/>
7+
<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">
8+
<mxGeometry x="460" y="-10" width="120" height="60" as="geometry"/>
9+
</mxCell>
10+
<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">
11+
<mxGeometry relative="1" as="geometry"/>
12+
</mxCell>
13+
<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">
14+
<mxGeometry x="340" y="90" width="360" height="230" as="geometry"/>
15+
</mxCell>
16+
<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">
17+
<mxGeometry x="355" y="120" width="330" height="28" as="geometry"/>
18+
</mxCell>
19+
<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">
20+
<mxGeometry x="355" y="163" width="330" height="28" as="geometry"/>
21+
</mxCell>
22+
<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">
23+
<mxGeometry x="355" y="240" width="330" height="28" as="geometry"/>
24+
</mxCell>
25+
<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">
26+
<mxGeometry x="355" y="279" width="330" height="28" as="geometry"/>
27+
</mxCell>
28+
<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">
29+
<mxGeometry relative="1" as="geometry"/>
30+
</mxCell>
31+
<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">
32+
<mxGeometry x="440" y="350" width="160" height="60" as="geometry"/>
33+
</mxCell>
34+
<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">
35+
<mxGeometry relative="1" as="geometry"/>
36+
</mxCell>
37+
<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">
38+
<mxGeometry x="355" y="440" width="330" height="45" as="geometry"/>
39+
</mxCell>
40+
<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">
41+
<mxGeometry relative="1" as="geometry"/>
42+
</mxCell>
43+
<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">
44+
<mxGeometry x="340" y="520" width="360" height="210" as="geometry"/>
45+
</mxCell>
46+
<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">
47+
<mxGeometry x="360" y="548" width="320" height="20" as="geometry"/>
48+
</mxCell>
49+
<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">
50+
<mxGeometry x="360" y="573" width="320" height="25" as="geometry"/>
51+
</mxCell>
52+
<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">
53+
<mxGeometry x="360" y="603" width="320" height="25" as="geometry"/>
54+
</mxCell>
55+
<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">
56+
<mxGeometry x="360" y="633" width="320" height="25" as="geometry"/>
57+
</mxCell>
58+
<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">
59+
<mxGeometry x="360" y="663" width="320" height="25" as="geometry"/>
60+
</mxCell>
61+
<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">
62+
<mxGeometry x="360" y="693" width="320" height="25" as="geometry"/>
63+
</mxCell>
64+
<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">
65+
<mxGeometry relative="1" as="geometry"/>
66+
</mxCell>
67+
<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">
68+
<mxGeometry x="340" y="760" width="360" height="130" as="geometry"/>
69+
</mxCell>
70+
<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">
71+
<mxGeometry x="360" y="790" width="320" height="25" as="geometry"/>
72+
</mxCell>
73+
<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">
74+
<mxGeometry x="360" y="820" width="320" height="25" as="geometry"/>
75+
</mxCell>
76+
<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">
77+
<mxGeometry x="360" y="850" width="320" height="25" as="geometry"/>
78+
</mxCell>
79+
<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">
80+
<mxGeometry x="740" y="580" width="280" height="100" as="geometry"/>
81+
</mxCell>
82+
<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">
83+
<mxGeometry x="20" y="780" width="280" height="80" as="geometry"/>
84+
</mxCell>
85+
<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">
86+
<mxGeometry x="355" y="200" width="330" height="28" as="geometry"/>
87+
</mxCell>
88+
</root>
89+
</mxGraphModel>
90+
</diagram>
91+
</mxfile>

‎docs/release-workflow-diagram.svg‎

Lines changed: 1 addition & 0 deletions
Loading

‎release-please-config.json‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -24,10 +24,7 @@
2424
"component": "project"
2525
},
2626
"packages/cli": {
27-
"component": "cli",
28-
"extra-files": [
29-
"npm-shrinkwrap.json"
30-
]
27+
"component": "cli"
3128
}
3229
},
3330
"plugins": [

0 commit comments

Comments
 (0)