@releasekit/notes 0.42.1 → 0.43.1

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.
@@ -1,403 +0,0 @@
1
- # Notes Configuration Reference
2
-
3
- All options live under the `notes` key in `releasekit.config.json`. Add `$schema` for editor autocompletion:
4
-
5
- ```json
6
- {
7
- "$schema": "https://goosewobbler.github.io/releasekit/schema.json",
8
- "notes": {}
9
- }
10
- ```
11
-
12
- ---
13
-
14
- ## `notes.changelog`
15
-
16
- Controls whether and where changelog files are written.
17
-
18
- **Type:** `false | object`
19
- **Default:** generates `CHANGELOG.md` at the repo root
20
-
21
- Set to `false` to disable changelog generation entirely.
22
-
23
- ```json
24
- {
25
- "notes": {
26
- "changelog": false
27
- }
28
- }
29
- ```
30
-
31
- When an object, the following properties are available:
32
-
33
- ### `notes.changelog.mode`
34
-
35
- | Value | Behaviour |
36
- |-------|-----------|
37
- | `"root"` | Write a single changelog at the repo root (default) |
38
- | `"packages"` | Write one changelog per package inside each package directory |
39
- | `"both"` | Write both root and per-package changelogs |
40
-
41
- ```json
42
- {
43
- "notes": {
44
- "changelog": { "mode": "packages" }
45
- }
46
- }
47
- ```
48
-
49
- ### `notes.changelog.file`
50
-
51
- Override the changelog file name.
52
-
53
- **Type:** `string`
54
- **Default:** `"CHANGELOG.md"`
55
-
56
- ```json
57
- {
58
- "notes": {
59
- "changelog": { "mode": "root", "file": "CHANGES.md" }
60
- }
61
- }
62
- ```
63
-
64
- ### `notes.changelog.templates`
65
-
66
- Custom template for changelog rendering.
67
-
68
- | Property | Type | Description |
69
- |----------|------|-------------|
70
- | `path` | `string` | Path to a template file or directory |
71
- | `engine` | `"handlebars" \| "liquid" \| "ejs"` | Template engine |
72
-
73
- ```json
74
- {
75
- "notes": {
76
- "changelog": {
77
- "mode": "root",
78
- "templates": {
79
- "path": "./templates/changelog/",
80
- "engine": "liquid"
81
- }
82
- }
83
- }
84
- }
85
- ```
86
-
87
- See the [templates guide](./templates.md) for authoring details.
88
-
89
- ---
90
-
91
- ## `notes.releaseNotes`
92
-
93
- Controls release notes generation. Release notes are a separate output from the changelog — typically prose-formatted and suitable for GitHub release bodies.
94
-
95
- **Type:** `false | object`
96
- **Default:** `undefined` (release notes not generated)
97
-
98
- Set to `false` to explicitly disable when it has been enabled via config inheritance.
99
-
100
- Release notes are **not** a changelog. By default they have no file — the generated content is passed to the publish step for the GitHub release body. In-repo file output is opt-in via `file.dir`.
101
-
102
- ### `notes.releaseNotes.file`
103
-
104
- Optional in-repo file output. Omit to keep release notes only on the GitHub release body (the default). When set, writes one **immutable file per version** under `dir`:
105
-
106
- | Layout | Path |
107
- |--------|------|
108
- | Monorepo | `release-notes/<package>/<version>.md` |
109
- | Single-package repo | `release-notes/<version>.md` |
110
-
111
- Each release writes a new file keyed by version, so prior releases are never overwritten — a browsable, provider-independent per-release history (the primary target for non-GitHub projects).
112
-
113
- | Option | Type | Default |
114
- |--------|------|---------|
115
- | `dir` | `string` | `"release-notes"` |
116
-
117
- ```json
118
- {
119
- "notes": {
120
- "releaseNotes": {
121
- "file": { "dir": "release-notes" }
122
- }
123
- }
124
- }
125
- ```
126
-
127
- ### `notes.releaseNotes.templates`
128
-
129
- Same structure as `notes.changelog.templates`. Renders each release's notes; for versioned files it's also the hook for docs-site frontmatter. Takes precedence over LLM prose and the default formatted section. See the [templates guide](./templates.md).
130
-
131
- ### `notes.releaseNotes.llm`
132
-
133
- LLM configuration for release notes enhancement. Requires `provider` and `model`.
134
-
135
- ```json
136
- {
137
- "notes": {
138
- "releaseNotes": {
139
- "llm": {
140
- "provider": "openai",
141
- "model": "<your-model>",
142
- "tasks": { "enhance": true, "summarize": true }
143
- }
144
- }
145
- }
146
- }
147
- ```
148
-
149
- See the [full LLM option reference](#llm-options-notesreleasenotesllm) below.
150
-
151
- ### `notes.releaseNotes.links`
152
-
153
- Appends a links section to each release in the built-in markdown renderer. Only rendered when LLM categorisation is active (`tasks.categorize: true`).
154
-
155
- | Option | Type | Description |
156
- |--------|------|-------------|
157
- | `title` | `string` | Section heading. Default: `"Links"` |
158
- | `items` | `object[]` | Static links: `{ label: string, url: string }` |
159
- | `fromPRBodyMarker` | `string` | Scan PR bodies for lines beginning with this marker and extract markdown links or bare URLs |
160
-
161
- ```json
162
- {
163
- "notes": {
164
- "releaseNotes": {
165
- "links": {
166
- "title": "Migration guide",
167
- "items": [
168
- { "label": "v2.0 migration", "url": "https://docs.example.com/migrate-v2" }
169
- ],
170
- "fromPRBodyMarker": "Migration:"
171
- }
172
- }
173
- }
174
- }
175
- ```
176
-
177
- Links discovered via `fromPRBodyMarker` are de-duplicated against explicit `items` by URL (explicit `items` take precedence).
178
-
179
- ---
180
-
181
- ## `notes.updateStrategy`
182
-
183
- How existing changelog files are updated when new entries are generated.
184
-
185
- **Type:** `"prepend" | "regenerate"`
186
- **Default:** `"prepend"`
187
-
188
- | Value | Behaviour |
189
- |-------|-----------|
190
- | `"prepend"` | New entries are inserted at the top of the existing file |
191
- | `"regenerate"` | The entire file is rewritten from scratch using all available history |
192
-
193
- ```json
194
- {
195
- "notes": {
196
- "updateStrategy": "regenerate"
197
- }
198
- }
199
- ```
200
-
201
- ---
202
-
203
- ## LLM options (`notes.releaseNotes.llm`)
204
-
205
- ### Required
206
-
207
- | Option | Type | Description |
208
- |--------|------|-------------|
209
- | `provider` | `string` | LLM provider key. See [LLM providers](./llm-providers.md). |
210
- | `model` | `string` | Model identifier for the selected provider (see [LLM providers](./llm-providers.md)). Required — releasekit ships no default, so pick a current model your provider serves. |
211
-
212
- ### Connection
213
-
214
- | Option | Type | Description |
215
- |--------|------|-------------|
216
- | `baseURL` | `string` | Custom API base URL (for `openai-compatible` providers) |
217
- | `apiKey` | `string` | API key inline. Prefer env var or `releasekit-notes auth` over this. |
218
-
219
- ### Behaviour
220
-
221
- | Option | Type | Default | Description |
222
- |--------|------|---------|-------------|
223
- | `concurrency` | `integer` | `5` | Maximum parallel LLM requests when enhancing entries |
224
- | `examples` | `integer` | `3` | Past GitHub releases to fetch for few-shot style prompting (`0`–`5`; requires `GITHUB_TOKEN`) |
225
-
226
- ### Context (`context`)
227
-
228
- | Option | Type | Default | Description |
229
- |--------|------|---------|-------------|
230
- | `context.pullRequests` | `boolean` | `true` | Fetch linked PR bodies from GitHub for extra LLM context. Requires `GITHUB_TOKEN` or `GH_TOKEN`. |
231
-
232
- ### Model options (`options`)
233
-
234
- | Option | Type | Default | Description |
235
- |--------|------|---------|-------------|
236
- | `timeout` | `integer` (ms) | `60000` | Idle timeout: a streamed response fails only when nothing arrives for this long |
237
- | `maxTokens` | `integer` | `16384` | Maximum tokens to generate |
238
- | `temperature` | `number` | `0.7` | Sampling temperature (0–2) |
239
-
240
- ```json
241
- {
242
- "notes": {
243
- "releaseNotes": {
244
- "llm": {
245
- "provider": "openai",
246
- "model": "<your-model>",
247
- "options": { "temperature": 0.3, "maxTokens": 1000 }
248
- }
249
- }
250
- }
251
- }
252
- ```
253
-
254
- ### Tasks (`tasks`)
255
-
256
- | Task | Type | Description |
257
- |------|------|-------------|
258
- | `enhance` | `boolean` | Rewrite each entry description to be clearer and more user-facing |
259
- | `summarize` | `boolean` | Generate a one-paragraph summary of the release |
260
- | `categorize` | `boolean` | Group entries into semantic categories (default set: Breaking, New, Changed, Fixed, Developer) |
261
- | `releaseNotes` | `boolean` | Generate full prose release notes suitable for a GitHub release body |
262
-
263
- ### Categories (`categories`)
264
-
265
- Controls how the `categorize` task groups entries. When not set, the following defaults are used:
266
-
267
- | Name | Description |
268
- |------|-------------|
269
- | `Breaking` | Breaking changes that require user action to upgrade |
270
- | `New` | New features and capabilities |
271
- | `Changed` | Changes to existing functionality |
272
- | `Fixed` | Bug fixes |
273
- | `Developer` | Internal changes: CI, tooling, dependencies, refactoring |
274
-
275
- Override with a custom list:
276
-
277
- ```json
278
- {
279
- "llm": {
280
- "tasks": { "categorize": true },
281
- "categories": [
282
- { "name": "Features", "description": "New user-facing functionality" },
283
- { "name": "Bug Fixes", "description": "Corrections to existing behaviour" },
284
- { "name": "Performance", "description": "Speed or resource improvements" }
285
- ]
286
- }
287
- }
288
- ```
289
-
290
- Each category object:
291
-
292
- | Field | Required | Description |
293
- |-------|----------|-------------|
294
- | `name` | yes | Display name used in template rendering |
295
- | `description` | yes | Hint sent to the LLM to guide grouping |
296
- | `scopes` | no | Commit scopes that always map to this category |
297
-
298
- ### Category order (`categoryOrder`)
299
-
300
- Controls the order in which LLM-categorised sections are rendered. Categories not listed appear after the listed ones. The `Breaking` category is always pinned first even if omitted from this list.
301
-
302
- **Type:** `string[]`
303
- **Default:** none (LLM-returned order is preserved)
304
-
305
- ```json
306
- {
307
- "llm": {
308
- "categoryOrder": ["Breaking", "New", "Fixed", "Changed", "Developer"]
309
- }
310
- }
311
- ```
312
-
313
- ### Scope validation (`scopes`)
314
-
315
- Controls how the LLM assigns scopes to entries. Invalid scopes trigger a corrective retry; after all retries are exhausted the scope is cleared rather than causing a failure.
316
-
317
- **`scopes.mode`**
318
-
319
- | Value | Behaviour |
320
- |-------|-----------|
321
- | `unrestricted` | LLM assigns any scope it chooses (default) |
322
- | `none` | Scopes are disabled; all assigned scopes are cleared |
323
- | `restricted` | Only scopes in `rules.allowed` are permitted |
324
- | `packages` | Scopes must match package names (monorepo only) |
325
-
326
- **`scopes.rules`**
327
-
328
- | Option | Type | Default | Description |
329
- |--------|------|---------|-------------|
330
- | `allowed` | `string[]` | — | Allowed scope values when mode is `restricted` |
331
- | `caseSensitive` | `boolean` | `false` | Whether scope matching is case-sensitive |
332
-
333
- ```json
334
- {
335
- "llm": {
336
- "scopes": {
337
- "mode": "restricted",
338
- "rules": { "allowed": ["api", "ui", "core"] }
339
- }
340
- }
341
- }
342
- ```
343
-
344
- ### Style (`style`)
345
-
346
- A style instruction appended to every LLM prompt.
347
-
348
- Default:
349
- ```
350
- Write in past tense ("Added feature", not "Add feature"). Be concise and user-focused. Lead with the impact, not the implementation detail.
351
- ```
352
-
353
- Override to change tone:
354
-
355
- ```json
356
- {
357
- "llm": {
358
- "style": "Use concise, non-technical language suitable for end users."
359
- }
360
- }
361
- ```
362
-
363
- ### Retry (`retry`)
364
-
365
- | Option | Type | Default | Description |
366
- |--------|------|---------|-------------|
367
- | `maxAttempts` | `integer` | `3` | Maximum retries on failure |
368
- | `initialDelay` | `integer` (ms) | `1000` | Delay before first retry |
369
- | `maxDelay` | `integer` (ms) | `30000` | Maximum delay between retries |
370
- | `backoffFactor` | `number` | `2` | Exponential backoff multiplier |
371
-
372
- ### Prompt overrides (`prompts`)
373
-
374
- `prompts.instructions` appends extra text to the built-in system prompt for a task. The structured output contract is preserved, so this is safe to use with all tasks.
375
-
376
- Available keys:
377
-
378
- | Key | Applies to |
379
- |-----|-----------|
380
- | `enhance` | Standalone `enhance` task (when `categorize` is disabled) |
381
- | `categorize` | Standalone `categorize` task (when `enhance` is disabled) |
382
- | `enhanceAndCategorize` | Combined task (when both `enhance` and `categorize` are enabled) |
383
- | `summarize` | `summarize` task |
384
- | `releaseNotes` | `releaseNotes` task |
385
-
386
- ```json
387
- {
388
- "notes": {
389
- "releaseNotes": {
390
- "llm": {
391
- "prompts": {
392
- "instructions": {
393
- "enhance": "Write from the perspective of an end user, not a developer.",
394
- "releaseNotes": "Start with a one-sentence executive summary."
395
- }
396
- }
397
- }
398
- }
399
- }
400
- }
401
- ```
402
-
403
- See the [LLM providers guide](./llm-providers.md) for more examples.