music-assistant-server

1# Release Notes Generation - Channel-Specific Behavior
2
3## Overview
4
5The release workflow generates release notes **specific to each channel** by leveraging Release Drafter's `filter-by-commitish` feature. This ensures that:
6
7- **Stable** releases only show commits from the `stable` branch
8- **Beta** releases only show commits from the `dev` branch since the last beta
9- **Nightly** releases only show commits from the `dev` branch since the last nightly
10
11The workflow uses the **release notes configuration** (`.github/release-notes-config.yml`) for label-based categorization and formatting.
12
13## How It Works
14
15### 1. Filter by Branch (commitish)
16
17The `.github/release-notes-config.yml` file includes:
18
19```yaml
20filter-by-commitish: true
21```
22
23This tells Release Drafter to only consider releases that have the same `target_commitish` (branch) when calculating the commit range. Combined with setting the `commitish` parameter to the appropriate branch:
24
25- **Stable releases**: Use `commitish: stable` → Only sees releases created from `stable` branch
26- **Beta releases**: Use `commitish: dev` → Only sees releases created from `dev` branch
27- **Nightly releases**: Use `commitish: dev` → Only sees releases created from `dev` branch
28
29### 2. Previous Release Detection
30
31The workflow also manually identifies the previous release for context headers using tag patterns:
32
33#### Stable Channel
34- **Pattern**: `^[0-9]+\.[0-9]+\.[0-9]+$` (e.g., `2.1.0`, `2.0.5`)
35- **Branch**: `stable`
36- **Finds**: Latest stable release (no suffix)
37
38#### Beta Channel
39- **Pattern**: `^[0-9]+\.[0-9]+\.[0-9]+b[0-9]+$` (e.g., `2.1.0b1`, `2.1.0b2`)
40- **Branch**: `dev`
41- **Finds**: Latest beta release (`bN` suffix)
42
43#### Nightly Channel
44- **Pattern**: `^[0-9]+\.[0-9]+\.[0-9]+\.dev[0-9]+$` (e.g., `2.1.0.dev20251023`)
45- **Branch**: `dev`
46- **Finds**: Latest nightly release (`.devYYYYMMDD` suffix)
47
48### 3. Release Notes Generation
49
50Release Drafter automatically:
51
521. **Finds commit range**: Determines commits between the previous release (same branch) and HEAD
532. **Extracts PRs**: Identifies all merged pull requests in that range
543. **Categorizes by labels**: Applies the category rules from `.github/release-notes-config.yml`:
55   - ⚠ Breaking Changes (`breaking-change` label)
56   - 🚀 New Providers (`new-provider` label)
57   - 🚀 Features and enhancements (`feature`, `enhancement`, `new-feature` labels)
58   - 🐛 Bugfixes (`bugfix` label)
59   - 🧰 Maintenance (`ci`, `documentation`, `maintenance`, `dependencies` labels)
604. **Lists contributors**: Adds all unique contributors from the PRs
61
62The workflow then enhances these notes by:
63- Adding a context header showing the previous release
64- Extracting and appending frontend changes from frontend update PRs
65- Merging and deduplicating contributors from both server and frontend
66
67### 4. What This Means
68
69#### ✅ Stable Release Notes
70- Include **only commits since the last stable release**
71- **Do NOT include** beta or nightly commits that happened in between
72- Example: `2.0.5` → `2.1.0` only shows stable branch commits
73
74#### ✅ Beta Release Notes
75- Include **only commits since the last beta release**
76- **Do NOT include** nightly commits
77- **Do NOT include** stable commits from stable branch
78- Example: `2.1.0b2` → `2.1.0b3` only shows dev branch commits since b2
79
80#### ✅ Nightly Release Notes
81- Include **only commits since the last nightly release**
82- **Do NOT include** beta or stable releases in between
83- Example: `2.1.0.dev20251022` → `2.1.0.dev20251023` only shows dev branch commits since yesterday
84
85## Release Notes Configuration
86
87✅ The workflow uses a **custom release notes generator** that reads `.github/release-notes-config.yml`:
88
89```yaml
90# .github/release-notes-config.yml
91change-template: '- $TITLE (by @$AUTHOR in #$NUMBER)'
92
93categories:
94  - title: "⚠ Breaking Changes"
95    labels: ['breaking-change']
96  # ... more categories
97```
98
99This approach ensures:
100- **Full control over commit range** (explicit previous tag parameter)
101- **No mysterious failures** (clear Python code you can debug)
102- **Consistent formatting** (same config format as Release Drafter used)
103- **Branch-based separation** (stable vs dev commits via explicit tag comparison)
104
105The configuration includes:
106- Category definitions (labels → section headers)
107- Category titles and emoji
108- Excluded contributors (bots)
109- PR title format
110- Collapse settings for long categories
111
112## Example Release Notes Format
113
114```markdown
115## 📦 Beta Release
116
117_Changes since [2.1.0b1](https://github.com/music-assistant/server/releases/tag/2.1.0b1)_
118
119### ⚠ Breaking Changes
120
121- Major API refactoring (by @contributor1 in #123)
122
123### 🚀 Features and enhancements
124
125- Add new audio processor (by @contributor2 in #124)
126- Improve queue management (by @contributor3 in #125)
127
128### 🐛 Bugfixes
129
130- Fix playback issue (by @contributor1 in #126)
131
132### 🧰 Maintenance and dependency bumps
133
134- Update dependencies (by @dependabot in #127)
135- Improve CI pipeline (by @contributor2 in #128)
136
137## :bow: Thanks to our contributors
138
139Special thanks to the following contributors who helped with this release:
140
141@contributor1, @contributor2, @contributor3
142```
143
144## Testing
145
146To verify channel-specific release notes:
147
1481. **Create a beta release** after a stable release:
149   ```bash
150   # Should only show commits on dev branch since last beta
151   # Should NOT include stable branch commits
152   ```
153
1542. **Create a nightly release** after a beta release:
155   ```bash
156   # Should only show commits since yesterday's nightly
157   # Should NOT include beta release notes
158   ```
159
1603. **Create a stable release** after multiple betas:
161   ```bash
162   # Should only show commits on stable branch since last stable
163   # Should NOT include any beta or nightly commits
164   ```
165
166## Verification Commands
167
168```bash
169# Check what will be in next stable release
170git log $(git tag | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)..stable --oneline
171
172# Check what will be in next beta release
173git log $(git tag | grep -E '^[0-9]+\.[0-9]+\.[0-9]+\.b[0-9]+$' | sort -V | tail -1)..dev --oneline
174
175# Check what will be in next nightly release
176git log $(git tag | grep -E '^[0-9]+\.[0-9]+\.[0-9]+\.dev[0-9]+$' | sort -V | tail -1)..dev --oneline
177```
178
179## Testing
180
181To verify channel-specific release notes:
182
1831. **Create a beta release** after a stable release:
184   ```bash
185   # Should only show commits on dev branch since last beta
186   # Should NOT include stable branch commits
187   ```
188
1892. **Create a nightly release** after a beta release:
190   ```bash
191   # Should only show commits since yesterday's nightly
192   # Should NOT include beta release notes
193   ```
194
1953. **Create a stable release** after multiple betas:
196   ```bash
197   # Should only show commits on stable branch since last stable
198   # Should NOT include any beta or nightly commits
199   ```
200
201## Verification Commands
202
203```bash
204# Check what will be in next stable release
205git log $(git tag | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)..stable --oneline
206
207# Check what will be in next beta release
208git log $(git tag | grep -E '^[0-9]+\.[0-9]+\.[0-9]+\.b[0-9]+$' | sort -V | tail -1)..dev --oneline
209
210# Check what will be in next nightly release
211git log $(git tag | grep -E '^[0-9]+\.[0-9]+\.[0-9]+\.dev[0-9]+$' | sort -V | tail -1)..dev --oneline
212```
213