Skip to content

Commit d0d13bf

Browse files
christian-byrnechristian-byrne
authored
[ci] standardize release notes format in release commands (#4912)
1 parent a1a8d48 commit d0d13bf

File tree

2 files changed

+133
-109
lines changed

2 files changed

+133
-109
lines changed

‎.claude/commands/create-frontend-release.md‎

Lines changed: 92 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -210,29 +210,52 @@ echo "Last stable release: $LAST_STABLE"
210210
echo "WARNING: PR #$PR not on main branch!"
211211
done
212212
```
213-
3. Create comprehensive release notes including:
214-
- **Version Change**: Show version bump details
215-
- **Changelog** grouped by type:
216-
- 🚀 **Features** (feat:)
217-
- 🐛 **Bug Fixes** (fix:)
218-
- 💥 **Breaking Changes** (BREAKING CHANGE)
219-
- 📚 **Documentation** (docs:)
220-
- 🔧 **Maintenance** (chore:, refactor:)
221-
- ⬆️ **Dependencies** (deps:, dependency updates)
222-
- **Litegraph Changes** (if version updated):
223-
- 🚀 Features: ${LITEGRAPH_FEATURES}
224-
- 🐛 Bug Fixes: ${LITEGRAPH_FIXES}
225-
- 💥 Breaking Changes: ${LITEGRAPH_BREAKING}
226-
- 🔧 Other Changes: ${LITEGRAPH_OTHER}
227-
- **Other Major Dependencies**: ${OTHER_DEP_CHANGES}
228-
- Include PR numbers and links
229-
- Add issue references (Fixes #123)
230-
4. **Save release notes:**
231-
```bash
232-
# Save release notes for PR and GitHub release
233-
echo "$RELEASE_NOTES" > release-notes-${NEW_VERSION}.md
234-
```
235-
5. **CONTENT REVIEW**: Release notes clear and comprehensive with dependency details?
213+
3. Create standardized release notes using this exact template:
214+
```bash
215+
cat > release-notes-${NEW_VERSION}.md << 'EOF'
216+
## ⚠️ Breaking Changes
217+
<!-- List breaking changes if any, otherwise remove this entire section -->
218+
- Breaking change description (#PR_NUMBER)
219+
220+
---
221+
222+
## What's Changed
223+
224+
### 🚀 Features
225+
<!-- List features here, one per line with PR reference -->
226+
- Feature description (#PR_NUMBER)
227+
228+
### 🐛 Bug Fixes
229+
<!-- List bug fixes here, one per line with PR reference -->
230+
- Bug fix description (#PR_NUMBER)
231+
232+
### 🔧 Maintenance
233+
<!-- List refactoring, chore, and other maintenance items -->
234+
- Maintenance item description (#PR_NUMBER)
235+
236+
### 📚 Documentation
237+
<!-- List documentation changes if any, remove section if empty -->
238+
- Documentation update description (#PR_NUMBER)
239+
240+
### ⬆️ Dependencies
241+
<!-- List dependency updates -->
242+
- Updated dependency from vX.X.X to vY.Y.Y (#PR_NUMBER)
243+
244+
**Full Changelog**: https://github.com/Comfy-Org/ComfyUI_frontend/compare/${BASE_TAG}...v${NEW_VERSION}
245+
EOF
246+
```
247+
4. **Parse commits and populate template:**
248+
- Group commits by conventional commit type (feat:, fix:, chore:, etc.)
249+
- Extract PR numbers from commit messages
250+
- For breaking changes, analyze if changes affect:
251+
- Public APIs (app object, api module)
252+
- Extension/workspace manager APIs
253+
- Node schema, workflow schema, or other public schemas
254+
- Any other public-facing interfaces
255+
- For dependency updates, list version changes with PR numbers
256+
- Remove empty sections (e.g., if no documentation changes)
257+
- Ensure consistent bullet format: `- Description (#PR_NUMBER)`
258+
5. **CONTENT REVIEW**: Release notes follow standard format?
236259
237260
### Step 9: Create Version Bump PR
238261
@@ -273,38 +296,12 @@ echo "Workflow triggered. Waiting for PR creation..."
273296
--body-file release-notes-${NEW_VERSION}.md \
274297
--label "Release"
275298
```
276-
3. **Add required sections to PR body:**
299+
3. **Update PR with release notes:**
277300
```bash
278-
# Create PR body with release notes plus required sections
279-
cat > pr-body.md << EOF
280-
${RELEASE_NOTES}
281-
282-
## Breaking Changes
283-
${BREAKING_CHANGES:-None}
284-
285-
## Testing Performed
286-
- ✅ Full test suite (unit, component)
287-
- ✅ TypeScript compilation
288-
- ✅ Linting checks
289-
- ✅ Build verification
290-
- ✅ Security audit
291-
292-
## Distribution Channels
293-
- GitHub Release (with dist.zip)
294-
- PyPI Package (comfyui-frontend-package)
295-
- npm Package (@comfyorg/comfyui-frontend-types)
296-
297-
## Post-Release Tasks
298-
- [ ] Verify all distribution channels
299-
- [ ] Update external documentation
300-
- [ ] Monitor for issues
301-
EOF
301+
# For workflow-created PRs, update the body with our release notes
302+
gh pr edit ${PR_NUMBER} --body-file release-notes-${NEW_VERSION}.md
302303
```
303-
4. Update PR with enhanced description:
304-
```bash
305-
gh pr edit ${PR_NUMBER} --body-file pr-body.md
306-
```
307-
5. **PR REVIEW**: Version bump PR created and enhanced correctly?
304+
4. **PR REVIEW**: Version bump PR created with standardized release notes?
308305
309306
### Step 10: Critical Release PR Verification
310307
@@ -592,55 +589,46 @@ The command implements multiple quality gates:
592589
- Draft release status
593590
- Python package specs require that prereleases use alpha/beta/rc as the preid
594591

595-
## Common Issues and Solutions
596-
597-
### Issue: Pre-release Version Confusion
598-
**Problem**: Not sure whether to promote pre-release or create new version
599-
**Solution**:
600-
- Follow semver standards: a prerelease version is followed by a normal release. It should have the same major, minor, and patch versions as the prerelease.
601-
602-
### Issue: Wrong Commit Count
603-
**Problem**: Changelog includes commits from other branches
604-
**Solution**: Always use `--first-parent` flag with git log
605-
606-
**Update**: Sometimes update-locales doesn't add [skip ci] - always verify!
607-
608-
### Issue: Missing PRs in Changelog
609-
**Problem**: PR was merged to different branch
610-
**Solution**: Verify PR merge target with:
611-
```bash
612-
gh pr view ${PR_NUMBER} --json baseRefName
613-
```
614-
615-
### Issue: Incomplete Dependency Changelog
616-
**Problem**: Litegraph or other dependency updates only show version bump, not actual changes
617-
**Solution**: The command now automatically:
618-
- Detects litegraph version changes between releases
619-
- Clones the litegraph repository temporarily
620-
- Extracts and categorizes changes between versions
621-
- Includes detailed litegraph changelog in release notes
622-
- Cleans up temporary files after analysis
623-
624-
### Issue: Release Failed Due to [skip ci]
625-
**Problem**: Release workflow didn't trigger after merge
626-
**Prevention**: Always avoid this scenario
627-
- Ensure that `[skip ci]` or similar flags are NOT in the `HEAD` commit message of the PR
628-
- Push a new, empty commit to the PR
629-
- Always double-check this immediately before merging
630-
631-
**Recovery Strategy**:
632-
1. Revert version in a new PR (e.g., 1.24.0 → 1.24.0-1)
633-
2. Merge the revert PR
634-
3. Run version bump workflow again
635-
4. This creates a fresh PR without [skip ci]
636-
Benefits: Cleaner than creating extra version numbers
637-
638-
## Key Learnings & Notes
639-
640-
1. **PR Author**: Version bump PRs are created by `comfy-pr-bot`, not `github-actions`
641-
2. **Workflow Speed**: Version bump workflow typically completes in ~20-30 seconds
642-
3. **Update-locales Behavior**: Inconsistent - sometimes adds [skip ci], sometimes doesn't
643-
4. **Recovery Options**: Reverting version is cleaner than creating extra versions
644-
5. **Dependency Tracking**: Command now automatically includes litegraph and major dependency changes in changelogs
645-
6. **Litegraph Integration**: Temporary cloning of litegraph repo provides detailed change analysis between versions
592+
## Critical Implementation Notes
593+
594+
When executing this release process, pay attention to these key aspects:
595+
596+
### Version Handling
597+
- For pre-release versions (e.g., 1.24.0-rc.1), the next stable release should be the same version without the suffix (1.24.0)
598+
- Never skip version numbers - follow semantic versioning strictly
599+
600+
### Commit History Analysis
601+
- **ALWAYS** use `--first-parent` flag with git log to avoid including commits from merged feature branches
602+
- Verify PR merge targets before including them in changelogs:
603+
```bash
604+
gh pr view ${PR_NUMBER} --json baseRefName
605+
```
606+
607+
### Release Workflow Triggers
608+
- The "Release" label on the PR is **CRITICAL** - without it, PyPI/npm publishing won't occur
609+
- Check for `[skip ci]` in commit messages before merging - this blocks the release workflow
610+
- If you encounter `[skip ci]`, push an empty commit to override it:
611+
```bash
612+
git commit --allow-empty -m "Trigger release workflow"
613+
```
614+
615+
### PR Creation Details
616+
- Version bump PRs come from `comfy-pr-bot`, not `github-actions`
617+
- The workflow typically completes in 20-30 seconds
618+
- Always wait for the PR to be created before trying to edit it
619+
620+
### Breaking Changes Detection
621+
- Analyze changes to public-facing APIs:
622+
- The `app` object and its methods
623+
- The `api` module exports
624+
- Extension and workspace manager interfaces
625+
- Node schema, workflow schema, and other public schemas
626+
- Any modifications to these require marking as breaking changes
627+
628+
### Recovery Procedures
629+
If the release workflow fails to trigger:
630+
1. Create a revert PR to restore the previous version
631+
2. Merge the revert
632+
3. Re-run the version bump workflow
633+
4. This approach is cleaner than creating extra version numbers
646634

‎.claude/commands/create-hotfix-release.md‎

Lines changed: 41 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -138,14 +138,50 @@ For each commit:
138138
```bash
139139
gh pr create --base core/X.Y --head release/1.23.5 \
140140
--title "[Release] v1.23.5" \
141-
--body "..." \
141+
--body "Release notes will be added shortly..." \
142142
--label "Release"
143143
```
144144
3. **CRITICAL**: Verify "Release" label is added
145-
4. PR description should include:
146-
- Version: `1.23.4` → `1.23.5`
147-
- Included fixes (link to previous PR)
148-
- Release notes for users
145+
4. Create standardized release notes:
146+
```bash
147+
cat > release-notes-${NEW_VERSION}.md << 'EOF'
148+
## ⚠️ Breaking Changes
149+
<!-- List breaking changes if any, otherwise remove this entire section -->
150+
- Breaking change description (#PR_NUMBER)
151+
152+
---
153+
154+
## What's Changed
155+
156+
### 🚀 Features
157+
<!-- List features here, one per line with PR reference -->
158+
- Feature description (#PR_NUMBER)
159+
160+
### 🐛 Bug Fixes
161+
<!-- List bug fixes here, one per line with PR reference -->
162+
- Bug fix description (#PR_NUMBER)
163+
164+
### 🔧 Maintenance
165+
<!-- List refactoring, chore, and other maintenance items -->
166+
- Maintenance item description (#PR_NUMBER)
167+
168+
### 📚 Documentation
169+
<!-- List documentation changes if any, remove section if empty -->
170+
- Documentation update description (#PR_NUMBER)
171+
172+
### ⬆️ Dependencies
173+
<!-- List dependency updates -->
174+
- Updated dependency from vX.X.X to vY.Y.Y (#PR_NUMBER)
175+
176+
**Full Changelog**: https://github.com/Comfy-Org/ComfyUI_frontend/compare/v${CURRENT_VERSION}...v${NEW_VERSION}
177+
EOF
178+
```
179+
- For hotfixes, typically only populate the "Bug Fixes" section
180+
- Include links to the cherry-picked PRs/commits
181+
- Update the PR body with the release notes:
182+
```bash
183+
gh pr edit ${PR_NUMBER} --body-file release-notes-${NEW_VERSION}.md
184+
```
149185
5. **CONFIRMATION REQUIRED**: Release PR has "Release" label?
150186
151187
### Step 11: Monitor Release Process

0 commit comments

Comments
 (0)