music-assistant-server

1# Custom Release Notes Generator
2
3## Overview
4
5We've replaced Release Drafter with a custom GitHub Action that generates release notes with full control over commit ranges and PR categorization.
6
7## Why Custom Solution?
8
9Release Drafter's `filter-by-commitish` feature proved unreliable:
10- Inconsistent handling of branch references (`dev` vs `refs/heads/dev`)
11- No way to explicitly specify the previous release tag
12- Would sometimes include entire git history instead of just changes since last release
13- Caused "body too long" errors when it tried to include all commits
14
15## How It Works
16
17### 1. Custom Action: `.github/actions/generate-release-notes/`
18
19This is a complete, self-contained GitHub Action that handles everything:
20
21**Inputs:**
22- `version`: The version being released
23- `previous-tag`: The previous release tag to compare against (optional)
24- `branch`: The branch being released from
25- `channel`: Release channel (stable/beta/nightly)
26- `github-token`: GitHub token for API access
27
28**Outputs:**
29- `release-notes`: Complete release notes including server changes, frontend changes, and merged contributors
30
31**What it does internally:**
321. Generates base release notes from server PRs
332. Extracts frontend changes from frontend update PRs
343. Merges contributors from both server and frontend
354. Returns complete, formatted release notes ready to publish
36
37### 2. Python Script: `generate_notes.py`
38
39The script:
401. **Loads configuration** from `.github/release-notes-config.yml`
412. **Fetches PRs** between the previous tag and current branch HEAD using GitHub API
423. **Categorizes PRs** based on labels:
43   - ⚠ Breaking Changes
44   - 🚀 New Providers
45   - 🚀 Features and enhancements
46   - 🐛 Bugfixes
47   - 🧰 Maintenance and dependency bumps
484. **Extracts contributors** excluding bots
495. **Formats notes** using templates from config
50
51### 3. Workflow Integration
52
53The release workflow is now incredibly simple:
541. **Detects previous tag** using channel-specific patterns
552. **Calls the action** with one step - that's it!
563. **Creates GitHub release** with the complete notes from the action
57
58All the complexity (server PRs, frontend PRs, contributor merging) is handled inside the reusable action.
59
60## Benefits
61
62✅ **Full control** - We explicitly specify which tag to compare against
63✅ **Reliable** - No mysterious "entire history" issues
64✅ **Consistent** - Uses same config format as Release Drafter
65✅ **Faster** - Only fetches the PRs we need
66✅ **Maintainable** - Clear Python code instead of black-box action
67✅ **Flexible** - Easy to customize formatting or add features
68
69## Configuration
70
71The generator reads `.github/release-notes-config.yml`:
72
73```yaml
74change-template: '- $TITLE (by @$AUTHOR in #$NUMBER)'
75
76exclude-contributors:
77  - dependabot
78  - dependabot[bot]
79  # ... more bots
80
81categories:
82  - title: "⚠ Breaking Changes"
83    labels:
84      - 'breaking-change'
85  - title: "🚀 Features and enhancements"
86    labels:
87      - 'feature'
88      - 'enhancement'
89  # ... more categories
90
91template: |
92  $CHANGES
93
94  ## :bow: Thanks to our contributors
95
96  Special thanks to the following contributors who helped with this release:
97
98  $CONTRIBUTORS
99```
100
101## Example Output
102
103```markdown
104## 📦 Nightly Release
105
106_Changes since [2.7.0.dev20251022](https://github.com/music-assistant/server/releases/tag/2.7.0.dev20251022)_
107
108### 🚀 Features and enhancements
109
110- Add new audio processor (by @contributor1 in #123)
111- Improve queue management (by @contributor2 in #124)
112
113### 🐛 Bugfixes
114
115- Fix playback issue (by @contributor1 in #125)
116
117## 🎨 Frontend Changes
118
119- Add dark mode toggle
120- Improve mobile layout
121- Fix typo in settings
122
123## :bow: Thanks to our contributors
124
125Special thanks to the following contributors who helped with this release:
126
127@contributor1, @contributor2, @frontend-contributor
128```
129
130## Testing
131
132To test locally:
133```bash
134cd .github/actions/generate-release-notes
135
136# Set environment variables
137export GITHUB_TOKEN="your_token"
138export VERSION="2.7.0.dev20251024"
139export PREVIOUS_TAG="2.7.0.dev20251023"
140export BRANCH="dev"
141export CHANNEL="nightly"
142export GITHUB_REPOSITORY="music-assistant/server"
143
144# Run the script
145python3 generate_notes.py
146```
147
148## Maintenance
149
150To modify release notes formatting:
1511. Edit `.github/release-notes-config.yml` to change categories, labels, or templates
1522. Edit `generate_notes.py` if you need to change the generation logic
1533. No changes needed to the main workflow unless adding new features
154
155## Configuration File Format
156
157The configuration file (`.github/release-notes-config.yml`) uses the same format as Release Drafter used to:
158- ✅ Same configuration structure
159- ✅ Same output formatting
160- ✅ Same contributor exclusion logic
161- ✅ Same label-based categorization
162
163But now we have **full control** over the commit range and complete visibility into the generation process.
164