Skip to content

Commit 31b5215

Browse files
d3xter666d3xter666
committed
docs: Add release please flow and config information
1 parent 38d475e commit 31b5215

File tree

3 files changed

+378
-0
lines changed

3 files changed

+378
-0
lines changed

‎docs/Release-Workflow.md‎

Lines changed: 286 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,286 @@
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+
The UI5 CLI uses an automated release workflow powered by Release Please to:
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**: Create/update release PR with version bumps and changelogs
29+
- **Output**: Information about created releases and PRs
30+
31+
### 2. Publish Packages Job
32+
- **Trigger**: When release PR is merged to `main`
33+
- **Action**: Developer merges the release PR in GitHub
34+
- **Result**:
35+
- Release Please creates releases & tags in GitHub for every package
36+
- Packages are published to npm sequentially (logger → fs → builder → server → project)
37+
- **Strategy**: Sequential execution (`max-parallel: 1`) to ensure dependencies exist before dependents
38+
39+
### 3. Publish CLI Job
40+
- **Trigger**: After all other packages are published
41+
- **Purpose**: Generate `npm-shrinkwrap.json` and publish the CLI package
42+
- **Dependency**: Requires all other packages to be available on npm registry
43+
44+
## Release Please Configuration
45+
46+
The configuration is defined in [`release-please-config.json`](../release-please-config.json). Below is a detailed explanation of each property:
47+
48+
49+
### Pull Request Title Pattern
50+
51+
```json
52+
"group-pull-request-title-pattern": "release: UI5 CLI packages ${branch}"
53+
```
54+
55+
**Purpose**: Defines the title format for release pull requests in monorepos.
56+
57+
**Behavior**:
58+
- Uses `${branch}` placeholder which gets replaced with the branch name
59+
- For linked versions, Release Please creates a single PR for all packages
60+
61+
**Documentation**: [Grouping Pull Requests](https://github.com/googleapis/release-please?tab=readme-ov-file#group-pull-request-title-pattern)
62+
63+
---
64+
65+
### Release Type
66+
67+
```json
68+
"release-type": "node"
69+
```
70+
71+
**Purpose**: Specifies the project type, which determines default behavior for versioning and changelog generation.
72+
73+
**Behavior**:
74+
- Uses Node.js/npm conventions
75+
- Updates `package.json` version field
76+
- Generates conventional changelog format
77+
- Handles npm-specific files
78+
79+
**Documentation**: [Release Types](https://github.com/googleapis/release-please?tab=readme-ov-file#release-types-supported)
80+
81+
---
82+
83+
### Always Update
84+
85+
```json
86+
"always-update": true
87+
```
88+
89+
**Purpose**: Ensures the release PR is updated with every commit to the main branch.
90+
91+
**Behavior**:
92+
- Scans commits since last release
93+
- Updates PR description, version numbers, and changelogs
94+
- Prevents stale release PRs
95+
96+
**Documentation**: This is a standard boolean flag in Release Please for keeping PRs current.
97+
98+
---
99+
100+
### Pull Request Header
101+
102+
```json
103+
"pull-request-header": ":tractor: New release prepared"
104+
```
105+
106+
**Purpose**: Customizes the header text in the release PR description.
107+
108+
**Behavior**:
109+
- Appears at the top of the release PR body
110+
- Can include emojis and markdown
111+
- Provides context to reviewers
112+
113+
**Documentation**: [Pull Request Header](https://github.com/googleapis/release-please?tab=readme-ov-file#pull-request-header)
114+
115+
---
116+
117+
### Prerelease Configuration
118+
119+
```json
120+
"prerelease": true,
121+
"prerelease-type": "alpha",
122+
"release-as": "5.0.0-alpha.0"
123+
```
124+
125+
**Purpose**: Configures prerelease versioning for alpha/beta releases.
126+
127+
**`prerelease`**:
128+
- Enables prerelease mode
129+
- Affects version bumping logic
130+
- [Documentation](https://github.com/googleapis/release-please?tab=readme-ov-file#prerelease)
131+
132+
**`prerelease-type`**:
133+
- Defines the prerelease identifier (alpha, beta, rc, etc.)
134+
- Appended to version: `5.0.0-alpha.0`, `5.0.0-alpha.1`, etc.
135+
- [Documentation](https://github.com/googleapis/release-please?tab=readme-ov-file#prerelease-type)
136+
137+
**`release-as`**:
138+
- Forces the next release version
139+
- Used for major version bumps or initial releases
140+
- Takes precedence over conventional commit version bumps
141+
- [Documentation](https://github.com/googleapis/release-please?tab=readme-ov-file#release-as)
142+
143+
---
144+
145+
### Packages
146+
147+
```json
148+
"packages": {
149+
"packages/logger": {
150+
"component": "logger"
151+
},
152+
"packages/cli": {
153+
"component": "cli",
154+
"extra-files": ["npm-shrinkwrap.json"]
155+
}
156+
}
157+
```
158+
159+
**Purpose**: Defines which packages in the monorepo should be managed by Release Please.
160+
161+
**Structure**:
162+
- **Key**: Path to package directory (relative to repo root)
163+
- **`component`**: Name used in changelog and release notes. Avoid scopes (@ui5) as it might tag something wrongly on GitHub
164+
- **`extra-files`**: Additional files to version bump (beyond `package.json`)
165+
166+
**Behavior**:
167+
- Each package gets its own changelog
168+
- Only specified packages are included in releases
169+
170+
**Documentation**: [Monorepo Support](https://github.com/googleapis/release-please?tab=readme-ov-file#monorepo-support)
171+
172+
**Note**: We explicitly configure packages instead of using `exclude-paths` because:
173+
1. More maintainable - clear list of released packages
174+
2. Prevents accidental inclusion of internal tooling
175+
3. Better for documentation and understanding
176+
177+
---
178+
179+
### Plugins
180+
181+
```json
182+
"plugins": [
183+
{
184+
"type": "node-workspace",
185+
"merge": false
186+
},
187+
{
188+
"type": "linked-versions",
189+
"groupName": "ui5-cli-packages",
190+
"components": ["logger", "fs", "builder", "server", "project", "cli"]
191+
}
192+
]
193+
```
194+
195+
**Purpose**: Extend Release Please functionality with additional behaviors.
196+
197+
#### Node Workspace Plugin
198+
199+
```json
200+
{
201+
"type": "node-workspace",
202+
"merge": false
203+
}
204+
```
205+
206+
**Purpose**: Automatically updates workspace dependency versions in `package.json` files.
207+
208+
**Behavior**:
209+
- Scans all `package.json` files in the workspace
210+
- Updates `dependencies` and `devDependencies` when workspace packages are bumped
211+
- `merge: false` means it updates versions but doesn't merge PRs automatically
212+
213+
**Known Limitations**:
214+
- Cannot resolve circular peer dependencies (e.g., `@ui5/project` ↔ `@ui5/builder`)
215+
- May update lockfile entries for npm aliases incorrectly
216+
217+
**Workaround**: We manually update circular peer dependencies in the workflow after Release Please runs.
218+
219+
**Documentation**: [Node Workspace Plugin](https://github.com/googleapis/release-please/blob/main/docs/plugins.md#node-workspace)
220+
221+
---
222+
223+
#### Linked Versions Plugin
224+
225+
```json
226+
{
227+
"type": "linked-versions",
228+
"groupName": "ui5-cli-packages",
229+
"components": ["logger", "fs", "builder", "server", "project", "cli"]
230+
}
231+
```
232+
233+
**Purpose**: Synchronizes version numbers across multiple packages in a monorepo.
234+
235+
**Behavior**:
236+
- All specified components get the same version number
237+
- Single release PR for all packages
238+
- Single GitHub release created for the group
239+
- Changelogs are still separate per package
240+
241+
**Benefits**:
242+
- Simplifies versioning for tightly coupled packages
243+
- Easier for consumers to know compatible versions
244+
- Reduces release management overhead
245+
246+
**Documentation**: [Linked Versions Plugin](https://github.com/googleapis/release-please/blob/main/docs/plugins.md#linked-versions)
247+
248+
---
249+
250+
### Changelog Sections
251+
252+
```json
253+
"changelog-sections": [
254+
{
255+
"type": "feat",
256+
"section": "Features"
257+
},
258+
{
259+
"type": "fix",
260+
"section": "Bug Fixes"
261+
},
262+
{
263+
"type": "docs",
264+
"section": "Documentation",
265+
"hidden": true
266+
}
267+
]
268+
```
269+
270+
**Purpose**: Defines which commit types appear in the changelog and how they're grouped.
271+
272+
**Structure**:
273+
- **`type`**: Conventional commit type (feat, fix, docs, etc.)
274+
- **`section`**: Heading in the changelog
275+
- **`hidden`**: If `true`, commits won't appear in changelog but may still trigger version bumps
276+
277+
**Behavior**:
278+
- Only configured types are included
279+
- Types can be reordered by array position
280+
- Hidden types are useful for internal changes (tests, CI, etc.)
281+
282+
**Documentation**: [Changelog Sections](https://github.com/googleapis/release-please?tab=readme-ov-file#changelog-sections)
283+
284+
**Our Configuration**:
285+
- **Visible**: Features, Bug Fixes, Performance Improvements, Dependencies, Reverts
286+
- **Hidden**: Documentation, Styles, Refactoring, Tests, Build, CI, Release

‎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="342" dy="1550" 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 PR with version bumps" 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 peerDependency &amp;amp; lockfile 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; tags&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="360" y="440" width="320" 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 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)" 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 order" 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&lt;br&gt;&amp;nbsp;&amp;nbsp;to exist on npm registry&lt;br&gt;• Ensures production-only locked deps" 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="• Syncronizes 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>

0 commit comments

Comments
 (0)