@releasekit/notes 0.19.3 → 0.20.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -1
- package/dist/{aggregator-CGD3KEVU.js → aggregator-GXJXPM7O.js} +2 -2
- package/dist/{chunk-XMSBOPFR.js → chunk-L34QVI62.js} +1 -1
- package/dist/{chunk-77FGMGVD.js → chunk-QCJ545PJ.js} +163 -10
- package/dist/{chunk-C4MRRHW7.js → chunk-UWUSIQSW.js} +953 -328
- package/dist/cli.js +2 -2
- package/dist/index.js +3 -3
- package/docs/configuration.md +139 -22
- package/docs/llm-providers.md +53 -19
- package/docs/llm-release-notes.md +464 -0
- package/docs/templates.md +33 -5
- package/package.json +2 -1
|
@@ -0,0 +1,464 @@
|
|
|
1
|
+
# LLM-Enhanced Release Notes
|
|
2
|
+
|
|
3
|
+
The LLM pipeline transforms raw conventional commit entries into polished, user-readable release notes. It can rewrite entry descriptions for clarity, group them into semantic categories, generate scannable `leadIn` phrases for notable features, automatically route breaking changes, and produce full prose release notes suitable for a GitHub release body. See [LLM providers](./llm-providers.md) for provider setup and authentication.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Setup
|
|
8
|
+
|
|
9
|
+
Add an `llm` block under `notes.releaseNotes` in `releasekit.config.json`:
|
|
10
|
+
|
|
11
|
+
```json
|
|
12
|
+
{
|
|
13
|
+
"notes": {
|
|
14
|
+
"releaseNotes": {
|
|
15
|
+
"llm": {
|
|
16
|
+
"provider": "openai",
|
|
17
|
+
"model": "gpt-4o-mini",
|
|
18
|
+
"tasks": { "enhance": true, "categorize": true }
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
> Without a `mode` or `file` property on `releaseNotes`, no file is written — the generated content is passed directly to the publish step (e.g. as a GitHub release body). Add `"mode": "root"` to also write a `RELEASE_NOTES.md` file.
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## What the LLM changes
|
|
30
|
+
|
|
31
|
+
Without LLM, the built-in renderer groups entries by their conventional commit type:
|
|
32
|
+
|
|
33
|
+
```markdown
|
|
34
|
+
## [2.0.0] - 2026-01-15
|
|
35
|
+
|
|
36
|
+
### Changed
|
|
37
|
+
- rename connect() to initialize() across public API
|
|
38
|
+
|
|
39
|
+
### Added
|
|
40
|
+
- add triggerDeeplink() for deep link testing
|
|
41
|
+
- add mock IPC handler support
|
|
42
|
+
|
|
43
|
+
### Fixed
|
|
44
|
+
- null pointer in renderer process memory management
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
With `enhance + categorize` enabled, the same commits produce:
|
|
48
|
+
|
|
49
|
+
```markdown
|
|
50
|
+
## [2.0.0] - 2026-01-15
|
|
51
|
+
|
|
52
|
+
### Breaking
|
|
53
|
+
- **BREAKING** **API rename**: Rename connect() to initialize()
|
|
54
|
+
|
|
55
|
+
### New
|
|
56
|
+
**ipc**:
|
|
57
|
+
- **Deeplink testing**: Add deep link support via triggerDeeplink()
|
|
58
|
+
- Add mock IPC support
|
|
59
|
+
|
|
60
|
+
### Fixed
|
|
61
|
+
- Resolve memory leak in renderer process
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
The LLM rewrites descriptions, groups by user intent instead of commit type, generates scannable `leadIn` phrases for notable entries, and routes breaking changes to a dedicated section.
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## Tasks
|
|
69
|
+
|
|
70
|
+
Four tasks are available. Any combination can be enabled simultaneously.
|
|
71
|
+
|
|
72
|
+
| Task | What it does | Output location |
|
|
73
|
+
|------|-------------|-----------------|
|
|
74
|
+
| `enhance` | Rewrites entry descriptions to be clear and user-facing | `entries[].description` (replaced in-place) |
|
|
75
|
+
| `categorize` | Groups entries into semantic categories | `enhanced.categories` in template context |
|
|
76
|
+
| `summarize` | Generates a 2–3 sentence release summary | `enhanced.summary` in template context |
|
|
77
|
+
| `releaseNotes` | Writes full prose markdown release notes | `enhanced.releaseNotes` / pipeline result |
|
|
78
|
+
|
|
79
|
+
**Recommended starting point:** Enable `enhance` and `categorize` together. This is the most impactful combination — rewriting and grouping both happen in a single LLM call, and it also unlocks `leadIn` phrases, scope grouping, and breaking change re-routing in the built-in renderer. Add `summarize` or `releaseNotes` when you want prose output for GitHub releases.
|
|
80
|
+
|
|
81
|
+
> **Efficiency tip:** When both `enhance` and `categorize` are enabled, the pipeline makes a **single combined LLM call** (`enhanceAndCategorize`) instead of two sequential calls. This combined path also produces `leadIn` phrases and scope assignments, which are not available when running `enhance` alone.
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## Task: `enhance`
|
|
86
|
+
|
|
87
|
+
Rewrites each changelog entry description to be clear, concise, and user-focused.
|
|
88
|
+
|
|
89
|
+
**Input:** `"fix: npe in auth middleware when token is null"`
|
|
90
|
+
**Output:** `"Fix crash during authentication when no token is provided"`
|
|
91
|
+
|
|
92
|
+
Entries are processed in parallel. Control the batch size with `concurrency` (default: `5`):
|
|
93
|
+
|
|
94
|
+
```json
|
|
95
|
+
{ "concurrency": 3 }
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
> **Note:** `leadIn` phrases, scope assignments, and breaking flags are only generated when `enhance` is combined with `categorize` (the combined `enhanceAndCategorize` path). Running `enhance` alone rewrites descriptions only — see [Combined enhance + categorize](#combined-enhance--categorize).
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## Task: `categorize`
|
|
103
|
+
|
|
104
|
+
Groups entries into user-friendly categories. The result populates `enhanced.categories` in the template context and drives the built-in markdown renderer's section layout.
|
|
105
|
+
|
|
106
|
+
### Default categories
|
|
107
|
+
|
|
108
|
+
When `categories` is not configured, the following defaults are used:
|
|
109
|
+
|
|
110
|
+
| Name | Description |
|
|
111
|
+
|------|-------------|
|
|
112
|
+
| `Breaking` | Breaking changes that require user action to upgrade |
|
|
113
|
+
| `New` | New features and capabilities |
|
|
114
|
+
| `Changed` | Changes to existing functionality |
|
|
115
|
+
| `Fixed` | Bug fixes |
|
|
116
|
+
| `Developer` | Internal changes: CI, tooling, dependencies, refactoring |
|
|
117
|
+
|
|
118
|
+
The LLM is constrained to these exact names. If the model returns an invalid category, the pipeline sends a follow-up message pointing out the error and asking it to revise — this is called a corrective retry. If all retries are exhausted, all entries are placed in a single `"General"` fallback category.
|
|
119
|
+
|
|
120
|
+
### Custom categories
|
|
121
|
+
|
|
122
|
+
Override the defaults by providing your own category list (shown as `notes.releaseNotes.llm` fragment):
|
|
123
|
+
|
|
124
|
+
```json
|
|
125
|
+
{
|
|
126
|
+
"tasks": { "categorize": true },
|
|
127
|
+
"categories": [
|
|
128
|
+
{ "name": "Features", "description": "New user-facing functionality" },
|
|
129
|
+
{ "name": "Bug Fixes", "description": "Corrections to existing behaviour" },
|
|
130
|
+
{ "name": "Under the Hood", "description": "Internal changes users may not notice" }
|
|
131
|
+
]
|
|
132
|
+
}
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Each category object:
|
|
136
|
+
|
|
137
|
+
| Field | Required | Description |
|
|
138
|
+
|-------|----------|-------------|
|
|
139
|
+
| `name` | yes | Display name used in section headers |
|
|
140
|
+
| `description` | yes | Hint sent to the LLM to guide grouping |
|
|
141
|
+
| `scopes` | no | Scope values that always map to this category |
|
|
142
|
+
|
|
143
|
+
### Category order
|
|
144
|
+
|
|
145
|
+
Control the render order with `categoryOrder`. Categories not in the list appear after the listed ones. The `Breaking` category always pins first even if omitted.
|
|
146
|
+
|
|
147
|
+
```json
|
|
148
|
+
{
|
|
149
|
+
"llm": {
|
|
150
|
+
"categoryOrder": ["Breaking", "New", "Fixed", "Changed", "Developer"]
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## Task: `summarize`
|
|
158
|
+
|
|
159
|
+
Generates a 2–3 sentence summary of the entire release. The result is available as `enhanced.summary` in the template context.
|
|
160
|
+
|
|
161
|
+
```json
|
|
162
|
+
{ "tasks": { "summarize": true } }
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## Task: `releaseNotes`
|
|
168
|
+
|
|
169
|
+
Generates complete prose markdown release notes for the version — suitable for a GitHub release body. The result is available as `enhanced.releaseNotes` in the pipeline result, and is used automatically when `publish.githubRelease.body` is set to `"releaseNotes"`.
|
|
170
|
+
|
|
171
|
+
```json
|
|
172
|
+
{ "tasks": { "releaseNotes": true } }
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
No `mode` or `file` is required for this task — the generated text is passed through the pipeline even without file output.
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
179
|
+
## Combined enhance + categorize
|
|
180
|
+
|
|
181
|
+
When both `enhance: true` and `categorize: true` are set, the pipeline runs a single `enhanceAndCategorize` call that returns:
|
|
182
|
+
|
|
183
|
+
- Rewritten `description` for each entry
|
|
184
|
+
- Assigned `category`
|
|
185
|
+
- Assigned `scope` (or `null`)
|
|
186
|
+
- `breaking` flag (or `null`)
|
|
187
|
+
- `leadIn` phrase (or `null`)
|
|
188
|
+
|
|
189
|
+
This is more efficient than two sequential calls and produces richer output. Use the `enhanceAndCategorize` key in `prompts.instructions` to customise this combined call — the standalone `enhance` key applies only when `categorize` is disabled:
|
|
190
|
+
|
|
191
|
+
```json
|
|
192
|
+
{
|
|
193
|
+
"llm": {
|
|
194
|
+
"prompts": {
|
|
195
|
+
"instructions": {
|
|
196
|
+
"enhanceAndCategorize": "Prefer 'New' over 'Changed' for purely additive changes.",
|
|
197
|
+
"enhance": "This applies only when categorize is disabled."
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
---
|
|
205
|
+
|
|
206
|
+
## Breaking change handling
|
|
207
|
+
|
|
208
|
+
Any entry where `breaking: true` is set — whether from the source input or flagged by the LLM during enhancement — is automatically moved to a `Breaking` category by the built-in markdown renderer at render time, regardless of which category the LLM assigned it to. If no `Breaking` category exists, one is created and prepended before all other categories.
|
|
209
|
+
|
|
210
|
+
This happens in the renderer, not during the LLM call, so custom templates receive the raw data and must implement breaking-change handling themselves if needed.
|
|
211
|
+
|
|
212
|
+
Rendered format:
|
|
213
|
+
- With `leadIn`: `- **BREAKING** **API rename**: Rename connect() to initialize()`
|
|
214
|
+
- Without `leadIn`: `- **BREAKING** Rename connect() to initialize()`
|
|
215
|
+
|
|
216
|
+
---
|
|
217
|
+
|
|
218
|
+
## `leadIn` phrases
|
|
219
|
+
|
|
220
|
+
When running the combined `enhanceAndCategorize` task, the LLM generates a `leadIn` phrase for notable entries — a short noun phrase (e.g. `"Streaming API"`, `"Deeplink testing"`) that makes the entry scannable at a glance.
|
|
221
|
+
|
|
222
|
+
The LLM sets `leadIn` only for entries that introduce a named API, feature, or concept. Routine fixes, dependency bumps, and internal refactors receive `null` and render without a prefix.
|
|
223
|
+
|
|
224
|
+
Rendered format:
|
|
225
|
+
- With `leadIn`: `- **Deeplink testing**: Add deep link support via triggerDeeplink()`
|
|
226
|
+
- Without `leadIn`: `- Add mock IPC support`
|
|
227
|
+
- With `leadIn` + `breaking`: `- **BREAKING** **API rename**: Rename connect() to initialize()`
|
|
228
|
+
|
|
229
|
+
The `leadIn` value is available in templates as `entry.leadIn` (may be `undefined`).
|
|
230
|
+
|
|
231
|
+
---
|
|
232
|
+
|
|
233
|
+
## Scope grouping
|
|
234
|
+
|
|
235
|
+
When the built-in markdown renderer encounters a category where **two or more entries share the same scope**, it groups them under a bold scope header instead of repeating the scope on each bullet:
|
|
236
|
+
|
|
237
|
+
```markdown
|
|
238
|
+
### New
|
|
239
|
+
**ipc**:
|
|
240
|
+
- **Deeplink testing**: Add deep link support via triggerDeeplink()
|
|
241
|
+
- Add mock IPC support
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
A scope that appears on only one entry renders inline: `- **scope**: description`. Entries with no scope render as plain bullets.
|
|
245
|
+
|
|
246
|
+
Scope is assigned by the LLM (or inherited from the source commit). Control what scopes are valid with the `scopes` config.
|
|
247
|
+
|
|
248
|
+
---
|
|
249
|
+
|
|
250
|
+
## Scope validation (`scopes`)
|
|
251
|
+
|
|
252
|
+
Controls how the LLM assigns scopes to entries.
|
|
253
|
+
|
|
254
|
+
| Mode | Behaviour |
|
|
255
|
+
|------|-----------|
|
|
256
|
+
| `unrestricted` | LLM assigns any scope it chooses (default) |
|
|
257
|
+
| `none` | Scopes are disabled; all assigned scopes are cleared |
|
|
258
|
+
| `restricted` | Only scopes in `rules.allowed` are permitted |
|
|
259
|
+
| `packages` | Scopes must match package names (monorepo only) |
|
|
260
|
+
|
|
261
|
+
```json
|
|
262
|
+
{
|
|
263
|
+
"llm": {
|
|
264
|
+
"scopes": {
|
|
265
|
+
"mode": "restricted",
|
|
266
|
+
"rules": {
|
|
267
|
+
"allowed": ["api", "ui", "core"],
|
|
268
|
+
"caseSensitive": false
|
|
269
|
+
}
|
|
270
|
+
}
|
|
271
|
+
}
|
|
272
|
+
}
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
Invalid scopes trigger a corrective retry — the LLM is told which scopes are valid and asked to revise its response. After all retry attempts are exhausted, the invalid scope is cleared rather than causing a failure.
|
|
276
|
+
|
|
277
|
+
---
|
|
278
|
+
|
|
279
|
+
## PR body context (`context.pullRequests`)
|
|
280
|
+
|
|
281
|
+
When `context.pullRequests` is `true` (the default), the pipeline fetches the body of each linked pull request from GitHub and includes it in the LLM prompt. This gives the LLM additional context — PR descriptions, linked issues, migration notes — for writing accurate enhanced entries.
|
|
282
|
+
|
|
283
|
+
Requires `GITHUB_TOKEN` or `GH_TOKEN`. If no token is available, PR fetching is silently skipped and a warning is logged.
|
|
284
|
+
|
|
285
|
+
Set to `false` to disable:
|
|
286
|
+
|
|
287
|
+
```json
|
|
288
|
+
{ "context": { "pullRequests": false } }
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
---
|
|
292
|
+
|
|
293
|
+
## Few-shot examples (`examples`)
|
|
294
|
+
|
|
295
|
+
The pipeline fetches up to `examples` (default: `3`) past GitHub releases and includes them in the LLM prompt as style references. The LLM uses the format and tone of prior releases to make new output consistent with your project's history.
|
|
296
|
+
|
|
297
|
+
```json
|
|
298
|
+
{ "examples": 5 }
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
Allowable range: `0`–`5`. Set to `0` to disable. Requires `GITHUB_TOKEN` or `GH_TOKEN` and a valid `repoUrl` in the input. Fetching is skipped silently if neither is available.
|
|
302
|
+
|
|
303
|
+
---
|
|
304
|
+
|
|
305
|
+
## Writing style (`style`)
|
|
306
|
+
|
|
307
|
+
The `style` string is appended to every LLM prompt as a style instruction. Default:
|
|
308
|
+
|
|
309
|
+
```
|
|
310
|
+
Write in past tense ("Added feature", not "Add feature"). Be concise and user-focused. Lead with the impact, not the implementation detail.
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
Override to change tone or focus:
|
|
314
|
+
|
|
315
|
+
```json
|
|
316
|
+
{
|
|
317
|
+
"llm": {
|
|
318
|
+
"style": "Use friendly language for non-technical users. Keep entries under 15 words."
|
|
319
|
+
}
|
|
320
|
+
}
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
---
|
|
324
|
+
|
|
325
|
+
## Links section (`notes.releaseNotes.links`)
|
|
326
|
+
|
|
327
|
+
The built-in renderer can append a links section at the bottom of each release. This section is only rendered when LLM categorisation is active (`tasks.categorize: true`).
|
|
328
|
+
|
|
329
|
+
Two sources of links can be combined:
|
|
330
|
+
|
|
331
|
+
- **`items`** — static label/URL pairs hardcoded in config
|
|
332
|
+
- **`fromPRBodyMarker`** — scans all linked PR bodies for lines starting with the marker string and extracts markdown links or bare URLs from them
|
|
333
|
+
|
|
334
|
+
```json
|
|
335
|
+
{
|
|
336
|
+
"notes": {
|
|
337
|
+
"releaseNotes": {
|
|
338
|
+
"links": {
|
|
339
|
+
"title": "Migration guide",
|
|
340
|
+
"items": [
|
|
341
|
+
{ "label": "v2.0 migration", "url": "https://docs.example.com/migrate-v2" }
|
|
342
|
+
],
|
|
343
|
+
"fromPRBodyMarker": "Migration:"
|
|
344
|
+
}
|
|
345
|
+
}
|
|
346
|
+
}
|
|
347
|
+
}
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
Rendered output:
|
|
351
|
+
|
|
352
|
+
```markdown
|
|
353
|
+
### Migration guide
|
|
354
|
+
- [v2.0 migration](https://docs.example.com/migrate-v2)
|
|
355
|
+
- [Full guide](https://docs.example.com/full-guide)
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
Links are de-duplicated by URL. Explicit `items` take precedence over discovered links. The `title` defaults to `"Links"` if not set.
|
|
359
|
+
|
|
360
|
+
---
|
|
361
|
+
|
|
362
|
+
## Prompt customisation
|
|
363
|
+
|
|
364
|
+
Override the built-in prompt instructions for any task using `prompts.instructions`. The string is appended to the relevant system prompt.
|
|
365
|
+
|
|
366
|
+
```json
|
|
367
|
+
{
|
|
368
|
+
"llm": {
|
|
369
|
+
"prompts": {
|
|
370
|
+
"instructions": {
|
|
371
|
+
"enhance": "Write from the perspective of an end user, not a developer.",
|
|
372
|
+
"enhanceAndCategorize": "Prefer 'New' over 'Changed' for additive changes. Flag any database migrations as breaking.",
|
|
373
|
+
"categorize": "When enhance is disabled, this key applies to the standalone categorize call.",
|
|
374
|
+
"summarize": "Write a single sentence, not a paragraph.",
|
|
375
|
+
"releaseNotes": "Start with a one-sentence executive summary, then group changes by theme."
|
|
376
|
+
}
|
|
377
|
+
}
|
|
378
|
+
}
|
|
379
|
+
}
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
Key clarification: `enhanceAndCategorize` applies when **both** `enhance: true` and `categorize: true` are set (the combined single-call path). The `enhance` key applies only when `categorize` is disabled.
|
|
383
|
+
|
|
384
|
+
---
|
|
385
|
+
|
|
386
|
+
## Error handling and fallback
|
|
387
|
+
|
|
388
|
+
The LLM pipeline is designed to be non-blocking. All failures are handled gracefully:
|
|
389
|
+
|
|
390
|
+
| Failure | Behaviour |
|
|
391
|
+
|---------|-----------|
|
|
392
|
+
| Provider unreachable, auth error, or unexpected exception | Warning logged; pipeline falls back to non-LLM rendering (type-based grouping) |
|
|
393
|
+
| Categorisation fails after all corrective retries | All entries placed in a single `"General"` category |
|
|
394
|
+
| Individual `enhance` entry fails | Original entry description preserved for that entry |
|
|
395
|
+
| Scope validation fails after all retries | Invalid scope cleared; entry rendered without scope |
|
|
396
|
+
|
|
397
|
+
Set `RELEASEKIT_DEBUG=1` for verbose LLM request/response logging.
|
|
398
|
+
|
|
399
|
+
---
|
|
400
|
+
|
|
401
|
+
## Full example
|
|
402
|
+
|
|
403
|
+
### Input entries
|
|
404
|
+
|
|
405
|
+
```
|
|
406
|
+
refactor!: rename connect() to initialize() across public API
|
|
407
|
+
feat(ipc): add triggerDeeplink() for deep link testing
|
|
408
|
+
feat(ipc): add mock IPC handler support
|
|
409
|
+
fix: null pointer in renderer process memory management
|
|
410
|
+
chore: migrate bundler from webpack to esbuild 0.20
|
|
411
|
+
```
|
|
412
|
+
|
|
413
|
+
### Config
|
|
414
|
+
|
|
415
|
+
```json
|
|
416
|
+
{
|
|
417
|
+
"notes": {
|
|
418
|
+
"releaseNotes": {
|
|
419
|
+
"llm": {
|
|
420
|
+
"provider": "anthropic",
|
|
421
|
+
"model": "claude-haiku-4-5",
|
|
422
|
+
"tasks": { "enhance": true, "categorize": true },
|
|
423
|
+
"categoryOrder": ["Breaking", "New", "Fixed", "Changed", "Developer"]
|
|
424
|
+
},
|
|
425
|
+
"links": {
|
|
426
|
+
"fromPRBodyMarker": "Migration:",
|
|
427
|
+
"items": [{ "label": "v2.0 migration guide", "url": "https://docs.example.com/migrate-v2" }]
|
|
428
|
+
}
|
|
429
|
+
}
|
|
430
|
+
}
|
|
431
|
+
}
|
|
432
|
+
```
|
|
433
|
+
|
|
434
|
+
Note that `links` is a property of `releaseNotes`, not `llm`.
|
|
435
|
+
|
|
436
|
+
### Rendered output
|
|
437
|
+
|
|
438
|
+
```markdown
|
|
439
|
+
## [2.0.0] - 2026-01-15
|
|
440
|
+
|
|
441
|
+
### Breaking
|
|
442
|
+
- **BREAKING** **API rename**: Rename connect() to initialize()
|
|
443
|
+
|
|
444
|
+
### New
|
|
445
|
+
**ipc**:
|
|
446
|
+
- **Deeplink testing**: Add deep link support via triggerDeeplink()
|
|
447
|
+
- Add mock IPC support
|
|
448
|
+
|
|
449
|
+
### Fixed
|
|
450
|
+
- Resolve memory leak in renderer process
|
|
451
|
+
|
|
452
|
+
### Developer
|
|
453
|
+
- Migrate bundler to esbuild 0.20
|
|
454
|
+
|
|
455
|
+
### Links
|
|
456
|
+
- [v2.0 migration guide](https://docs.example.com/migrate-v2)
|
|
457
|
+
```
|
|
458
|
+
|
|
459
|
+
**What happened:**
|
|
460
|
+
- The `refactor!` commit has `breaking: true`, so it was re-routed to `Breaking` regardless of the LLM's original category. The `leadIn` phrase `"API rename"` was generated because it introduces a named API change.
|
|
461
|
+
- The two `feat(ipc)` commits share the `ipc` scope, so they're grouped under a `**ipc**:` header. The first gets a `leadIn` (`"Deeplink testing"`); the second is a routine addition and gets none.
|
|
462
|
+
- The `fix` commit maps to `Fixed` with no scope or `leadIn` (routine fix).
|
|
463
|
+
- The `chore` commit maps to `Developer` (internal tooling change).
|
|
464
|
+
- The static link from `items` is appended under `### Links`.
|
package/docs/templates.md
CHANGED
|
@@ -44,7 +44,7 @@ Pass a directory containing named template files. Each file renders a different
|
|
|
44
44
|
templates/
|
|
45
45
|
├── document.liquid # Outer document wrapper (receives DocumentContext)
|
|
46
46
|
├── version.liquid # One version block (receives TemplateContext)
|
|
47
|
-
└── entry.liquid # One changelog entry (receives ChangelogEntry)
|
|
47
|
+
└── entry.liquid # One changelog entry (receives ChangelogEntry fields directly)
|
|
48
48
|
```
|
|
49
49
|
|
|
50
50
|
```bash
|
|
@@ -53,6 +53,8 @@ releasekit-notes --template ./templates/
|
|
|
53
53
|
|
|
54
54
|
All three files are optional — omit any you don't need to customise, and the built-in for that level is used.
|
|
55
55
|
|
|
56
|
+
The `entry.liquid` template receives the `ChangelogEntry` fields directly as top-level variables: `type`, `description`, `scope`, `breaking`, `issueIds`, `leadIn`.
|
|
57
|
+
|
|
56
58
|
---
|
|
57
59
|
|
|
58
60
|
## Template Context
|
|
@@ -92,10 +94,11 @@ Each entry in `entries` has:
|
|
|
92
94
|
| Field | Type | Values |
|
|
93
95
|
|-------|------|--------|
|
|
94
96
|
| `type` | `ChangelogType` | `"added"`, `"changed"`, `"deprecated"`, `"removed"`, `"fixed"`, `"security"` |
|
|
95
|
-
| `description` | `string` | Entry description (
|
|
96
|
-
| `scope` | `string \| undefined` | Conventional commit scope |
|
|
97
|
+
| `description` | `string` | Entry description (rewritten by LLM if `tasks.enhance` is on) |
|
|
98
|
+
| `scope` | `string \| undefined` | Conventional commit scope (may be assigned or validated by LLM) |
|
|
97
99
|
| `breaking` | `boolean \| undefined` | `true` for breaking changes |
|
|
98
100
|
| `issueIds` | `string[] \| undefined` | Referenced issue/PR numbers |
|
|
101
|
+
| `leadIn` | `string \| undefined` | Short scannable phrase for notable entries (e.g. `"Streaming API"`). Set by the LLM during `enhance` or combined `enhanceAndCategorize`. `undefined` for routine entries. |
|
|
99
102
|
|
|
100
103
|
### Enhanced data (`enhanced`)
|
|
101
104
|
|
|
@@ -103,7 +106,8 @@ Present when any LLM task ran successfully:
|
|
|
103
106
|
|
|
104
107
|
| Field | Type | Description |
|
|
105
108
|
|-------|------|-------------|
|
|
106
|
-
| `enhanced.
|
|
109
|
+
| `enhanced.entries` | `ChangelogEntry[]` | Entries with rewritten `description` fields (`enhance` task) |
|
|
110
|
+
| `enhanced.summary` | `string \| undefined` | 2–3 sentence release summary (`summarize` task) |
|
|
107
111
|
| `enhanced.categories` | `Category[] \| undefined` | Grouped entries (`categorize` task) |
|
|
108
112
|
| `enhanced.releaseNotes` | `string \| undefined` | Full prose release notes (`releaseNotes` task) |
|
|
109
113
|
|
|
@@ -112,7 +116,21 @@ Each `Category` in `enhanced.categories`:
|
|
|
112
116
|
| Field | Type | Description |
|
|
113
117
|
|-------|------|-------------|
|
|
114
118
|
| `name` | `string` | Category display name |
|
|
115
|
-
| `entries` | `ChangelogEntry[]` | Entries in this category |
|
|
119
|
+
| `entries` | `ChangelogEntry[]` | Entries in this category (same type as `entries`; may have `leadIn`, `scope`, `breaking` populated by the LLM) |
|
|
120
|
+
|
|
121
|
+
Entries within `enhanced.categories` are the same `ChangelogEntry` objects as in `entries`, with all LLM-assigned fields populated. Custom templates can access `entry.leadIn`, `entry.scope`, and `entry.breaking` directly.
|
|
122
|
+
|
|
123
|
+
### Built-in renderer behaviour
|
|
124
|
+
|
|
125
|
+
When no custom template is configured, the built-in markdown renderer applies the following transformations to LLM-categorised output. Custom templates receive the raw data and must implement these behaviours themselves if desired.
|
|
126
|
+
|
|
127
|
+
**Scope grouping:** Within a category, entries sharing the same scope value (two or more) are rendered under a `**scope**:` group header. Entries with a unique scope render with the scope inline (`**scope**: description`). Entries with no scope render as plain bullets.
|
|
128
|
+
|
|
129
|
+
**Breaking change re-routing:** Any entry with `breaking: true` is moved to a `Breaking` category at render time, regardless of which category the LLM assigned it to. If no `Breaking` category exists, one is created and prepended before all other categories.
|
|
130
|
+
|
|
131
|
+
**`leadIn` prefix:** Entries with a `leadIn` value render as `**leadIn**: description`. Combined with `breaking: true`, the format is `**BREAKING** **leadIn**: description`.
|
|
132
|
+
|
|
133
|
+
**Links section:** When `notes.releaseNotes.links` is configured, a links section is appended after all categories. This section is only rendered in the LLM-categorised path.
|
|
116
134
|
|
|
117
135
|
---
|
|
118
136
|
|
|
@@ -147,7 +165,17 @@ Each `Category` in `enhanced.categories`:
|
|
|
147
165
|
### {{ cat.name }}
|
|
148
166
|
|
|
149
167
|
{% for entry in cat.entries %}
|
|
168
|
+
{% if entry.breaking and entry.leadIn %}
|
|
169
|
+
- **BREAKING** **{{ entry.leadIn }}**: {{ entry.description }}
|
|
170
|
+
{% elsif entry.breaking %}
|
|
171
|
+
- **BREAKING** {{ entry.description }}
|
|
172
|
+
{% elsif entry.leadIn %}
|
|
173
|
+
- **{{ entry.leadIn }}**: {{ entry.description }}
|
|
174
|
+
{% elsif entry.scope %}
|
|
175
|
+
- **{{ entry.scope }}**: {{ entry.description }}
|
|
176
|
+
{% else %}
|
|
150
177
|
- {{ entry.description }}
|
|
178
|
+
{% endif %}
|
|
151
179
|
{% endfor %}
|
|
152
180
|
{% endfor %}
|
|
153
181
|
{% else %}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@releasekit/notes",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.20.0",
|
|
4
4
|
"description": "Release notes and changelog generation with LLM-powered enhancement and flexible templating",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"module": "./dist/index.js",
|
|
@@ -48,6 +48,7 @@
|
|
|
48
48
|
},
|
|
49
49
|
"dependencies": {
|
|
50
50
|
"@anthropic-ai/sdk": "^0.86.0",
|
|
51
|
+
"@octokit/request-error": "^7.1.0",
|
|
51
52
|
"@octokit/rest": "^22.0.1",
|
|
52
53
|
"chalk": "^5.6.2",
|
|
53
54
|
"commander": "^14.0.3",
|