Skip to content

Commit dc6bbe7

Browse files
SoWieMarkusPhilippMatthes
SoWieMarkus
and
PhilippMatthes
authored
Add changelog update command and workflow for release PRs (#746)
Add changelog command and workflow that is triggered on PR closed on release. --------- Co-authored-by: Philipp Matthes <27271818+PhilippMatthes@users.noreply.github.com> Co-authored-by: Philipp Matthes <p.matthes@sap.com>
1 parent 1c7250e commit dc6bbe7

4 files changed

Lines changed: 271 additions & 1 deletion

File tree

‎.claude/commands/release.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
---
2+
allowed-tools: Read, Write, Edit, Bash(*), WebSearch, WebFetch, Agent
3+
description: Release orchestrator — builds a digest of what changed in a release PR, opens a changelog PR, and references the bump PR. Usage: /release PR_NUMBER
4+
---
5+
6+
# Release Orchestrator
7+
8+
Your job is to orchestrate the release process for a given PR. This involves analyzing the PR's commits and changed files to build a structured digest of what changed, determining if there are any breaking changes, preparing a changelog, opening a PR to bump chart versions if needed, and updating the original PR description with the changelog and references to the new PRs.
9+
10+
---
11+
12+
## Phase 1: Collect — Build the release digest
13+
14+
1. Fetch PR metadata:
15+
```
16+
gh pr view $ARGUMENTS --json number,title,body,commits,files
17+
```
18+
19+
2. For each commit SHA in the PR, inspect the changed files:
20+
```
21+
git show --name-only --format="%H %s" <sha>
22+
```
23+
24+
3. Classify each commit to a component:
25+
- Cortex shim: code touching the shim layer (internal/shim and cmd/shim)
26+
- Cortex postgres: code touching the postgres docker image, or its helm chart
27+
- Cortex core: core code touching anything else: the manager or external scheduler logic of cortex
28+
- General: CI, tooling, docs, or other non-code changes
29+
30+
4. Finally, read through the cortex helm charts in the helm/ folder, and check which ones have updated appVersions, indicating a new Docker image is available and that the chart should be included in the release notes.
31+
32+
Produce a structured digest in this exact format — the subagents depend on it:
33+
34+
```
35+
## Release Digest — PR #NNN "{title}"
36+
37+
### Changed Charts
38+
- cortex v1.2.3 (sha-xxxxxxxx)
39+
- cortex-postgres v1.2.3 (sha-xxxxxxxx)
40+
- cortex-nova v1.2.3 — includes cortex v1.2.3, cortex-postgres v1.2.3
41+
42+
### Commits by Component
43+
44+
#### cortex core
45+
- <sha> <subject>
46+
47+
#### cortex postgres
48+
- <sha> <subject>
49+
50+
#### cortex shim
51+
- <sha> <subject>
52+
53+
#### General
54+
- <sha> <subject>
55+
```
56+
57+
**Important**: Do NOT skip or shallow this phase. Read actual file diffs. The subagents depend entirely on the quality of this digest.
58+
59+
---
60+
61+
## Phase 2: Determine Breaking Changes and Prepare a Changelog
62+
63+
Reason for each change by looking at the commit's diff, if it is a breaking change that requires special attention.
64+
65+
**Important**: Do NOT skip or shallow this phase. Read actual file diffs. The PR reviewers depend entirely on the quality of this analysis to know what to focus on in their review.
66+
67+
### When is a change "breaking"?
68+
69+
A change should be classified as "breaking" if it meets any of the following criteria:
70+
71+
- It changes or removes the public API of any component (e.g., CRD schemas, CLI flags, or REST API endpoints). Note: additions to the public API are not breaking.
72+
- It requires a config format change (e.g., renaming or removing a values.yaml key, changing the expected format of a value, etc)
73+
74+
Once the digest is complete, read each agent file, then dispatch all three **in parallel** using the Agent tool in a single message. Each subagent operates independently — do not wait for one before starting the others.
75+
76+
### Prepare the changelog
77+
78+
Generate a changelog following this template:
79+
80+
```markdown
81+
# Changelog
82+
83+
## YYYY-MM-DD — [#NNN](<PR URL>)
84+
85+
### <chart-name> v<version> (<appVersion>)
86+
87+
Breaking changes:
88+
- <bullet per meaningful change>
89+
90+
Non-breaking changes:
91+
- <bullet per meaningful change>
92+
93+
... repeat for each changed chart ...
94+
95+
### General
96+
97+
Breaking changes:
98+
- <bullet per meaningful change>
99+
100+
Non-breaking changes:
101+
- <bullet per meaningful change>
102+
```
103+
104+
One `###` section per changed chart only. For bundle sections, list which library versions they include, then any bundle-specific changes (values.yaml keys, template/CRD changes). Omit `### General` if empty. No commit SHAs, one line per bullet.
105+
106+
Example:
107+
```markdown
108+
# Changelog
109+
110+
## 2026-04-24 — [#123](https://github.com/cobaltcore-dev/cortex/pull/123)
111+
112+
### cortex v0.0.43 (sha-xxxxxxxx)
113+
114+
Breaking changes:
115+
- Check hypervisor resources against reservations
116+
117+
Non-breaking changes:
118+
- Commitments usage API uses postgres database instead of calling nova
119+
120+
### cortex-postgres v0.5.14 (sha-xxxxxxxx)
121+
122+
Non-breaking changes:
123+
- Add commitments table migration
124+
125+
### cortex-nova v0.0.56 (sha-xxxxxxxx)
126+
127+
Includes updated charts cortex v0.0.43 and cortex-postgres v0.5.14.
128+
129+
Non-breaking changes:
130+
- values.yaml: added `reservations.enabled` (default: false)
131+
132+
### General
133+
134+
Non-breaking changes:
135+
- Update golangci-lint to v2.1.0
136+
```
137+
138+
## Phase 3: Bump Chart Versions
139+
140+
Prepare chart version bumps so GitHub pushes bumped charts to the registry immediately after the release PR is merged.
141+
142+
For each changed library chart, patch-bump its `version` in `helm/library/<name>/Chart.yaml` (e.g. `0.0.43` → `0.1.0`), if there was no breaking change, otherwise minor-bump it. Do not touch `appVersion`. Then update the matching `dependencies[].version` entry in every `helm/bundles/*/Chart.yaml` that references it.
143+
144+
Open a single PR to `main` with all the bumps, branch `release/bump-charts-<NNN>`, noting in the body that it should be merged before the release PR. Use the pull-request-creator agent for this subtask, and include the chart changes in the motivation so they are included in the PR description.
145+
146+
## Phase 4: Update the PR Description
147+
148+
Use `gh pr edit` with `--body` to update the PR description with the changelog. It is fine for release pull request descriptions to utilize markdown formatting. Reference the opened bump PR in the description as well as a dependency.
149+
150+
## Phase 5: Create a Changelog PR
151+
152+
If the CHANGELOG.md does not exists, create it with a `# Changelog` header. Then create a new PR to `main` with branch `release/changelog-<NNN>`, title `Update changelog for release PR #<NNN>`, and a body noting it should be merged after the release PR. Use the pull-request-creator agent for this subtask.
153+
154+
## Phase 6: Summarize — Report what happened
155+
156+
After all subagents return, produce a short summary:
157+
158+
```
159+
## Release #NNN Post-Open Summary
160+
161+
- PR description updated with changelog and bump PR reference
162+
- Bump PR #XXX opened to update chart versions
163+
- Changelog PR #YYY opened to update CHANGELOG.md
164+
```

‎.claude/commands/update-changelog.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
allowed-tools: Read, Write, Edit, Bash(*), WebSearch, WebFetch
3+
description: Create a changelog entry for a merged release PR and open a PR to main. Usage: /update-changelog PR_NUMBER
4+
---
5+
6+
A release PR (#$ARGUMENTS) was merged into the `release` branch. Create a changelog entry for it and open a PR to `main`.
7+
8+
To build the entry, use the PR's commit subjects (no diffs) and the changed Helm charts as your sources. Only include charts whose Chart.yaml actually changed in this PR.
9+
10+
Format each entry as:
11+
12+
## {merged_at date in UTC, formatted YYYY-MM-DD} — {PR title} ([#NNN](https://github.com/cobaltcore-dev/cortex/pull/NNN))
13+
14+
One `###` section per changed chart: `### <chart-name> v<version> (<appVersion>)`
15+
Under each section, bullet the commit subjects that relate to that chart.
16+
17+
Attribution: for each commit, inspect its changed files with `git show --name-only <sha>` and map to the chart whose files were touched:
18+
19+
- `postgres/**` → cortex-postgres
20+
- `cmd/shim/**` or `internal/shim/**` → cortex-shim
21+
- `helm/bundles/cortex-<name>/**` → that specific bundle chart
22+
- anything else → cortex (core)
23+
24+
Commits that only touch CI, docs, or tooling go into `### General`. Skip commits containing "[skip ci]" or that are pure version-bump message.
25+
26+
For bundle chart sections (helm/bundles/*), add a note listing which library chart versions they now include (read the bundle's Chart.yaml dependencies). Then inspect the actual diff of the bundle's own files with `git show <sha> -- helm/bundles/<name>/` for any commit that touched that bundle, and surface specific changes:
27+
28+
- **values.yaml** changes: call out new, removed, or renamed keys and changed defaults
29+
- **templates/** or **crds/** changes: call out added, removed, or modified resources by kind and name
30+
31+
Prepend the new entry below the `# Changelog` header in `CHANGELOG.md` (create the file if it doesn't exist). Then open a PR to `main` referencing this release PR.
32+
33+
## Example
34+
35+
```markdown
36+
## 2026-04-24 — Release libs cortex v0.0.43 + bundles v0.0.56 ([#722](https://github.com/cobaltcore-dev/cortex/pull/722))
37+
38+
### cortex v0.0.43 (sha-xxxxxxxx)
39+
- Commitments usage API uses postgres database instead of calling nova
40+
- Check hypervisor resources against reservations
41+
- Add committed resource reservations to capacity calculation
42+
43+
### cortex-postgres v0.5.14 (sha-xxxxxxxx)
44+
- Add commitments table migration
45+
46+
### cortex-nova v0.0.56 (sha-xxxxxxxx)
47+
- Update nova bundle for committed reservations support
48+
49+
### cortex-manila v0.0.56 (sha-xxxxxxxx)
50+
- Update manila bundle for committed reservations support
51+
52+
### General
53+
- Update golangci-lint to v2.1.0
54+
```

‎.coderabbit.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
11
reviews:
2-
high_level_summary: false
2+
high_level_summary: false

‎.github/workflows/claude-release.yaml‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
name: Claude Code Release Orchestrator
2+
3+
on:
4+
pull_request:
5+
types: [opened, synchronize, reopened]
6+
branches:
7+
- release
8+
9+
jobs:
10+
release:
11+
if: false # Temporarily disabled
12+
runs-on: ubuntu-latest
13+
concurrency:
14+
group: changelog-release
15+
cancel-in-progress: false
16+
permissions:
17+
contents: write
18+
pull-requests: write
19+
id-token: write
20+
steps:
21+
- name: Checkout code
22+
uses: actions/checkout@v6
23+
24+
- name: Set up Go
25+
uses: actions/setup-go@v6
26+
with:
27+
go-version-file: 'go.mod'
28+
29+
- uses: ./.github/actions/setup-claude-code-action
30+
31+
- uses: ./.github/actions/start-litellm-proxy
32+
env:
33+
AICORE_RESOURCE_GROUP: ${{ secrets.AICORE_RESOURCE_GROUP }}
34+
AICORE_BASE_URL: ${{ secrets.AICORE_BASE_URL }}
35+
AICORE_AUTH_URL: ${{ secrets.AICORE_AUTH_URL }}
36+
AICORE_CLIENT_ID: ${{ secrets.AICORE_CLIENT_ID }}
37+
AICORE_CLIENT_SECRET: ${{ secrets.AICORE_CLIENT_SECRET }}
38+
39+
- uses: ./.claude-code-action
40+
with:
41+
claude_args: |
42+
--max-turns 1000
43+
--permission-mode auto
44+
--allowedTools "Read,Write,Edit,Bash(*),WebSearch,WebFetch,Agent"
45+
use_litellm: "true"
46+
litellm_model: "sap/anthropic--claude-4.6-opus"
47+
github_token: ${{ secrets.GITHUB_TOKEN }}
48+
show_full_output: "true"
49+
prompt: "/release ${{ github.event.pull_request.number }}"
50+
51+
- uses: ./.github/actions/stop-litellm-proxy
52+
if: always()

0 commit comments

Comments
 (0)