@releasekit/notes 0.44.1 → 0.46.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 +6 -6
- package/dist/{aggregator-JHRFNT67.js → aggregator-XM2XIYDF.js} +1 -2
- package/dist/{chunk-VD3TYCTF.js → chunk-EI7LLVJN.js} +294 -140
- package/dist/{chunk-KTLNPX37.js → chunk-JOA56Y7A.js} +261 -203
- package/dist/cli.js +2 -2
- package/dist/index.d.ts +108 -23
- package/dist/index.js +12 -10
- package/docs/llm-providers.md +7 -6
- package/docs/llm-release-notes.md +15 -39
- package/docs/monorepo.md +41 -0
- package/docs/templates.md +73 -58
- package/package.json +2 -2
- package/templates/angular/document.hbs +12 -0
- package/templates/angular/entry.hbs +1 -2
- package/templates/angular/version.hbs +14 -4
- package/templates/github-release/release.md.ejs +40 -15
- package/templates/keep-a-changelog/document.liquid +11 -0
- package/templates/keep-a-changelog/entry.liquid +1 -2
- package/templates/keep-a-changelog/version.liquid +19 -52
- package/dist/chunk-YCULLVSG.js +0 -150
package/dist/cli.js
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
import {
|
|
3
3
|
createNotesCommand
|
|
4
|
-
} from "./chunk-
|
|
4
|
+
} from "./chunk-JOA56Y7A.js";
|
|
5
5
|
import {
|
|
6
6
|
readPackageVersion
|
|
7
|
-
} from "./chunk-
|
|
7
|
+
} from "./chunk-EI7LLVJN.js";
|
|
8
8
|
|
|
9
9
|
// src/cli.ts
|
|
10
10
|
import * as fs from "fs";
|
package/dist/index.d.ts
CHANGED
|
@@ -11,6 +11,13 @@ declare function loadAuth(): Record<string, string>;
|
|
|
11
11
|
declare function saveAuth(provider: string, apiKey: string): void;
|
|
12
12
|
|
|
13
13
|
type ChangelogRefsMode = 'strip' | 'escape' | 'link';
|
|
14
|
+
interface BundledPackage<T> {
|
|
15
|
+
packageName: string;
|
|
16
|
+
/** Set when the package released more than once in the range. */
|
|
17
|
+
firstVersion?: string;
|
|
18
|
+
version: string;
|
|
19
|
+
entries: T[];
|
|
20
|
+
}
|
|
14
21
|
|
|
15
22
|
declare abstract class ReleaseKitError extends Error {
|
|
16
23
|
abstract readonly code: string;
|
|
@@ -41,6 +48,8 @@ interface VersionChangelogEntry {
|
|
|
41
48
|
* extraction-error fallback, which isn't a no-change carry.
|
|
42
49
|
*/
|
|
43
50
|
synthetic?: boolean;
|
|
51
|
+
/** On a `sharedEntries` entry: its commit touched a `sharedPackages` package. Absent for a repo-level entry. */
|
|
52
|
+
sharedPackage?: boolean;
|
|
44
53
|
}
|
|
45
54
|
interface VersionPackageChangelog {
|
|
46
55
|
packageName: string;
|
|
@@ -51,6 +60,23 @@ interface VersionPackageChangelog {
|
|
|
51
60
|
entries: VersionChangelogEntry[];
|
|
52
61
|
/** The tag this changelog releases: the package's own, or a sync release's shared one. Absent in older manifests. */
|
|
53
62
|
tag?: string;
|
|
63
|
+
/**
|
|
64
|
+
* Entries from commits in this changelog's range that touch a `sharedPackages` package and no non-shared package,
|
|
65
|
+
* leaving out commits under this package's own directories. Recorded, possibly empty, by async-mode releases with
|
|
66
|
+
* shared packages; absent otherwise and in older manifests.
|
|
67
|
+
*/
|
|
68
|
+
sharedPackageEntries?: VersionChangelogEntry[];
|
|
69
|
+
/** A primary's bundled packages, each with the versions of that package the primary's notes include, oldest first. */
|
|
70
|
+
bundled?: VersionBundledPackage[];
|
|
71
|
+
}
|
|
72
|
+
interface VersionBundledPackage {
|
|
73
|
+
packageName: string;
|
|
74
|
+
versions: string[];
|
|
75
|
+
}
|
|
76
|
+
interface VersionBundledRelease {
|
|
77
|
+
packageName: string;
|
|
78
|
+
version: string;
|
|
79
|
+
entries: VersionChangelogEntry[];
|
|
54
80
|
}
|
|
55
81
|
/** `'graduated'`: a prerelease promoted to stable, ignoring any requested bump. `'first-release'`: no prior tag. */
|
|
56
82
|
type VersionAction = 'first-release' | 'graduated' | 'bumped';
|
|
@@ -68,6 +94,11 @@ interface VersionOutput {
|
|
|
68
94
|
/** Entries from commits that touch no package outside `sharedPackages`, counting the directories a package
|
|
69
95
|
* versions through `cargo.paths` / `pub.paths`. */
|
|
70
96
|
sharedEntries?: VersionChangelogEntry[];
|
|
97
|
+
/**
|
|
98
|
+
* Earlier releases a primary's `bundled` packages made since its previous release, each stored once however many
|
|
99
|
+
* primaries include it. A bundled package's release in this run is its own changelog record.
|
|
100
|
+
*/
|
|
101
|
+
bundledReleases?: VersionBundledRelease[];
|
|
71
102
|
commitMessage?: string;
|
|
72
103
|
/** Consumer-facing tags from `tagTemplate`. */
|
|
73
104
|
tags: string[];
|
|
@@ -142,6 +173,8 @@ interface ChangelogEntry {
|
|
|
142
173
|
originalType?: string;
|
|
143
174
|
breaking?: boolean;
|
|
144
175
|
leadIn?: string;
|
|
176
|
+
/** On a project-wide entry: its commit touched a `sharedPackages` package, so every package's notes list it. */
|
|
177
|
+
sharedPackage?: boolean;
|
|
145
178
|
/** Populated upstream of LLM tasks; never serialised to disk. */
|
|
146
179
|
context?: {
|
|
147
180
|
prs: PRContext[];
|
|
@@ -156,11 +189,19 @@ interface PackageChangelog {
|
|
|
156
189
|
repoUrl: string | null;
|
|
157
190
|
date: string;
|
|
158
191
|
entries: ChangelogEntry[];
|
|
192
|
+
sharedPackageEntries?: ChangelogEntry[];
|
|
193
|
+
bundled?: VersionBundledPackage[];
|
|
159
194
|
}
|
|
195
|
+
type BundledRelease = Omit<VersionBundledRelease, 'entries'> & {
|
|
196
|
+
entries: ChangelogEntry[];
|
|
197
|
+
};
|
|
160
198
|
type InputSource = 'version';
|
|
161
199
|
interface ChangelogInput {
|
|
162
200
|
source: InputSource;
|
|
163
201
|
packages: PackageChangelog[];
|
|
202
|
+
/** Project-wide entries, from commits that touch no package outside `sharedPackages`. */
|
|
203
|
+
sharedEntries?: ChangelogEntry[];
|
|
204
|
+
bundledReleases?: BundledRelease[];
|
|
164
205
|
metadata?: {
|
|
165
206
|
repoUrl?: string;
|
|
166
207
|
defaultBranch?: string;
|
|
@@ -171,7 +212,6 @@ interface EnhancedCategory {
|
|
|
171
212
|
entries: ChangelogEntry[];
|
|
172
213
|
}
|
|
173
214
|
interface EnhancedData {
|
|
174
|
-
entries: ChangelogEntry[];
|
|
175
215
|
summary?: string;
|
|
176
216
|
categories?: EnhancedCategory[];
|
|
177
217
|
releaseNotes?: string;
|
|
@@ -186,15 +226,47 @@ interface TemplateContext {
|
|
|
186
226
|
compareUrl?: string;
|
|
187
227
|
enhanced?: EnhancedData;
|
|
188
228
|
isFirstRelease?: boolean;
|
|
229
|
+
/** Shared-package entries, listed after the version's own. */
|
|
230
|
+
sharedEntries?: ChangelogEntry[];
|
|
231
|
+
/** A primary's bundled packages. Release notes only: the changelog never lists them. */
|
|
232
|
+
bundled?: BundledPackage<ChangelogEntry>[];
|
|
233
|
+
}
|
|
234
|
+
interface TemplateEntry extends ChangelogEntry {
|
|
235
|
+
/** The built-in renderer's line: refs rendered, mentions and comment openers escaped. */
|
|
236
|
+
line: string;
|
|
237
|
+
}
|
|
238
|
+
interface TemplateSection {
|
|
239
|
+
label: string;
|
|
240
|
+
entries: TemplateEntry[];
|
|
241
|
+
}
|
|
242
|
+
/** What a template sees for one version. */
|
|
243
|
+
interface TemplateBundledPackage {
|
|
244
|
+
packageName: string;
|
|
245
|
+
/** Set when the package released more than once since the primary's previous release. */
|
|
246
|
+
firstVersion?: string;
|
|
247
|
+
version: string;
|
|
248
|
+
sections: TemplateSection[];
|
|
249
|
+
}
|
|
250
|
+
interface TemplateVersion extends Omit<TemplateContext, 'entries' | 'enhanced' | 'sharedEntries' | 'bundled'> {
|
|
251
|
+
entries: TemplateEntry[];
|
|
252
|
+
/** LLM categories when `categorize` ran, otherwise commit-type groups. Breaking leads unless `categoryOrder` places it. */
|
|
253
|
+
sections: TemplateSection[];
|
|
254
|
+
/** Shared-package entries in commit-type groups. Empty in a root changelog. */
|
|
255
|
+
shared: TemplateSection[];
|
|
256
|
+
/** A primary's bundled packages, each in commit-type groups. Empty outside release notes. */
|
|
257
|
+
bundled: TemplateBundledPackage[];
|
|
258
|
+
enhanced?: Omit<EnhancedData, 'categories'>;
|
|
189
259
|
}
|
|
190
260
|
interface DocumentContext {
|
|
191
261
|
project: {
|
|
192
262
|
name: string;
|
|
193
263
|
repoUrl?: string;
|
|
194
264
|
};
|
|
195
|
-
versions:
|
|
196
|
-
unreleased?:
|
|
265
|
+
versions: TemplateVersion[];
|
|
266
|
+
unreleased?: TemplateVersion;
|
|
197
267
|
compareUrls?: Record<string, string>;
|
|
268
|
+
/** A root changelog's project-wide entries for the run, in commit-type groups. Empty otherwise. */
|
|
269
|
+
shared: TemplateSection[];
|
|
198
270
|
/** Templates can use this to suppress document-level headings that are redundant
|
|
199
271
|
* when the content is embedded in a release that already shows the package/version. */
|
|
200
272
|
perPackage?: boolean;
|
|
@@ -232,12 +304,10 @@ interface ScopeConfig {
|
|
|
232
304
|
mode?: 'restricted' | 'packages' | 'none' | 'unrestricted';
|
|
233
305
|
rules?: ScopeRules;
|
|
234
306
|
}
|
|
235
|
-
type UpdateStrategy = 'prepend' | 'regenerate';
|
|
236
307
|
interface Config {
|
|
237
308
|
changelog?: false | ChangelogConfig;
|
|
238
309
|
releaseNotes?: false | ReleaseNotesConfig;
|
|
239
310
|
monorepo?: MonorepoConfig;
|
|
240
|
-
updateStrategy?: UpdateStrategy;
|
|
241
311
|
}
|
|
242
312
|
type JSONSchema = Record<string, unknown>;
|
|
243
313
|
interface CompleteOptions {
|
|
@@ -320,6 +390,19 @@ interface ReleaseNotesConfig {
|
|
|
320
390
|
declare function loadConfig(projectDir?: string, configFile?: string): Config;
|
|
321
391
|
declare function getDefaultConfig(): Config;
|
|
322
392
|
|
|
393
|
+
interface FormatVersionOptions {
|
|
394
|
+
includePackageName?: boolean;
|
|
395
|
+
/** Order to render LLM-categorised sections. */
|
|
396
|
+
categoryOrder?: string[];
|
|
397
|
+
links?: LinksConfig;
|
|
398
|
+
firstRelease?: FirstReleaseConfig | false;
|
|
399
|
+
refs?: ChangelogRefsMode;
|
|
400
|
+
}
|
|
401
|
+
declare function formatVersion(context: TemplateContext, options?: FormatVersionOptions): string;
|
|
402
|
+
/** `sharedEntries` are listed once, after the versions, under a dated heading of their own. */
|
|
403
|
+
declare function renderMarkdown(contexts: TemplateContext[], options?: FormatVersionOptions, sharedEntries?: ChangelogEntry[]): string;
|
|
404
|
+
declare function writeChangelog(outputPath: string, content: string, dryRun: boolean): void;
|
|
405
|
+
|
|
323
406
|
declare function createTemplateContext(pkg: PackageChangelog): TemplateContext;
|
|
324
407
|
interface PipelineResult {
|
|
325
408
|
/** Per-package rendered markdown keyed by package name. */
|
|
@@ -338,6 +421,11 @@ interface PipelineOptions {
|
|
|
338
421
|
skipReleaseNotes?: boolean;
|
|
339
422
|
/** Use during publish from manifest to regenerate only the release notes against an already-bumped tree. */
|
|
340
423
|
skipChangelogs?: boolean;
|
|
424
|
+
/**
|
|
425
|
+
* Generate release notes only for these packages, and no changelogs. The other packages still count toward the
|
|
426
|
+
* release-notes file layout.
|
|
427
|
+
*/
|
|
428
|
+
releaseNotesFor?: string[];
|
|
341
429
|
}
|
|
342
430
|
declare function runPipeline(input: ChangelogInput, config: Config, dryRun: boolean, pipelineOptions?: PipelineOptions): Promise<PipelineResult>;
|
|
343
431
|
declare function processInput(inputJson: string, config: Config, dryRun: boolean, pipelineOptions?: PipelineOptions): Promise<PipelineResult>;
|
|
@@ -376,7 +464,7 @@ declare class ConfigError extends NotesError {
|
|
|
376
464
|
}
|
|
377
465
|
declare function getExitCode(error: NotesError): number;
|
|
378
466
|
|
|
379
|
-
declare function versionOutputToChangelogInput(data: Pick<VersionOutput, 'changelogs'> & Partial<Pick<VersionOutput, 'updates' | 'tags'>>): ChangelogInput;
|
|
467
|
+
declare function versionOutputToChangelogInput(data: Pick<VersionOutput, 'changelogs'> & Partial<Pick<VersionOutput, 'updates' | 'tags' | 'sharedEntries' | 'bundledReleases'>>): ChangelogInput;
|
|
380
468
|
declare function parseVersionOutput(json: string): ChangelogInput;
|
|
381
469
|
declare function parseVersionOutputFile(filePath: string): ChangelogInput;
|
|
382
470
|
declare function parseVersionOutputStdin(): Promise<ChangelogInput>;
|
|
@@ -384,13 +472,10 @@ declare function parseVersionOutputStdin(): Promise<ChangelogInput>;
|
|
|
384
472
|
interface MonorepoOptions {
|
|
385
473
|
rootPath: string;
|
|
386
474
|
packagesPath: string;
|
|
387
|
-
mode: 'root' | 'packages' | 'both';
|
|
388
475
|
fileName?: string;
|
|
389
476
|
}
|
|
390
477
|
declare function aggregateToRoot(contexts: TemplateContext[]): TemplateContext;
|
|
391
|
-
declare function writeMonorepoChangelogs(contexts: TemplateContext[], options: MonorepoOptions,
|
|
392
|
-
updateStrategy?: 'prepend' | 'regenerate';
|
|
393
|
-
}, dryRun: boolean, refs?: ChangelogRefsMode): string[];
|
|
478
|
+
declare function writeMonorepoChangelogs(contexts: TemplateContext[], options: MonorepoOptions, render: (contexts: TemplateContext[]) => string, dryRun: boolean): string[];
|
|
394
479
|
declare function detectMonorepo(cwd: string): {
|
|
395
480
|
isMonorepo: boolean;
|
|
396
481
|
packagesPath: string;
|
|
@@ -399,17 +484,17 @@ declare function detectMonorepo(cwd: string): {
|
|
|
399
484
|
declare function renderJson(contexts: TemplateContext[]): string;
|
|
400
485
|
declare function writeJson(outputPath: string, contexts: TemplateContext[], dryRun: boolean): void;
|
|
401
486
|
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
487
|
+
/** `packageCount` is the release's, not the run's: see `writeVersionedNotes`. */
|
|
488
|
+
declare function nestsReleaseNotes(packageCount: number): boolean;
|
|
489
|
+
/**
|
|
490
|
+
* `nested` MUST reflect whether the *repo* has more than one package - not how many packages are in
|
|
491
|
+
* this run. An independently-versioned monorepo releases one package per pipeline invocation, so a
|
|
492
|
+
* flat path would silently overwrite another package that shares a version number.
|
|
493
|
+
*/
|
|
494
|
+
declare function writeVersionedNotes<T extends {
|
|
495
|
+
packageName: string;
|
|
496
|
+
version: string;
|
|
497
|
+
}>(contexts: T[], directory: string, dryRun: boolean, nested: boolean, renderContent: (ctx: T) => string): string[];
|
|
413
498
|
|
|
414
|
-
export { ConfigError, GitHubError, InputParseError, InputValidationError, LLMError, NotesError, TemplateError, aggregateToRoot, createTemplateContext, detectMonorepo, formatVersion, getDefaultConfig, getExitCode, loadAuth, loadConfig, parseVersionOutput, parseVersionOutputFile, parseVersionOutputStdin, processInput, renderJson, renderMarkdown, runPipeline, saveAuth, versionOutputToChangelogInput,
|
|
415
|
-
export type { ChangelogConfig, ChangelogEntry, ChangelogInput, ChangelogType, CompleteOptions, Config, DocumentContext, EnhancedCategory, EnhancedData, FirstReleaseConfig, InputSource, JSONSchema, LLMCategory, LLMConfig, LLMOptions, LLMPromptOverrides, LLMPromptsConfig, LinksConfig, LocationMode, PRContext, PackageChangelog, PipelineOptions, PipelineResult, ReleaseNotesConfig, ReleaseNotesFileConfig, RetryOptions, ScopeConfig, ScopeRules, TemplateConfig, TemplateContext, TemplateEngine,
|
|
499
|
+
export { ConfigError, GitHubError, InputParseError, InputValidationError, LLMError, NotesError, TemplateError, aggregateToRoot, createTemplateContext, detectMonorepo, formatVersion, getDefaultConfig, getExitCode, loadAuth, loadConfig, nestsReleaseNotes, parseVersionOutput, parseVersionOutputFile, parseVersionOutputStdin, processInput, renderJson, renderMarkdown, runPipeline, saveAuth, versionOutputToChangelogInput, writeChangelog, writeJson, writeMonorepoChangelogs, writeVersionedNotes };
|
|
500
|
+
export type { BundledRelease, ChangelogConfig, ChangelogEntry, ChangelogInput, ChangelogType, CompleteOptions, Config, DocumentContext, EnhancedCategory, EnhancedData, FirstReleaseConfig, InputSource, JSONSchema, LLMCategory, LLMConfig, LLMOptions, LLMPromptOverrides, LLMPromptsConfig, LinksConfig, LocationMode, PRContext, PackageChangelog, PipelineOptions, PipelineResult, ReleaseNotesConfig, ReleaseNotesFileConfig, RetryOptions, ScopeConfig, ScopeRules, TemplateBundledPackage, TemplateConfig, TemplateContext, TemplateEngine, TemplateEntry, TemplateSection, TemplateVersion };
|
package/dist/index.js
CHANGED
|
@@ -12,27 +12,27 @@ import {
|
|
|
12
12
|
getExitCode,
|
|
13
13
|
loadAuth,
|
|
14
14
|
loadConfig,
|
|
15
|
+
nestsReleaseNotes,
|
|
15
16
|
parseVersionOutput,
|
|
16
17
|
parseVersionOutputFile,
|
|
17
18
|
parseVersionOutputStdin,
|
|
18
19
|
processInput,
|
|
19
20
|
runPipeline,
|
|
20
21
|
saveAuth,
|
|
21
|
-
versionOutputToChangelogInput
|
|
22
|
-
|
|
22
|
+
versionOutputToChangelogInput,
|
|
23
|
+
writeVersionedNotes
|
|
24
|
+
} from "./chunk-JOA56Y7A.js";
|
|
23
25
|
import {
|
|
24
26
|
aggregateToRoot,
|
|
25
|
-
detectMonorepo,
|
|
26
|
-
writeMonorepoChangelogs
|
|
27
|
-
} from "./chunk-YCULLVSG.js";
|
|
28
|
-
import {
|
|
29
27
|
debug,
|
|
28
|
+
detectMonorepo,
|
|
30
29
|
formatVersion,
|
|
31
30
|
info,
|
|
32
31
|
renderMarkdown,
|
|
33
32
|
success,
|
|
34
|
-
|
|
35
|
-
|
|
33
|
+
writeChangelog,
|
|
34
|
+
writeMonorepoChangelogs
|
|
35
|
+
} from "./chunk-EI7LLVJN.js";
|
|
36
36
|
|
|
37
37
|
// src/output/json.ts
|
|
38
38
|
import * as fs from "fs";
|
|
@@ -86,6 +86,7 @@ export {
|
|
|
86
86
|
getExitCode,
|
|
87
87
|
loadAuth,
|
|
88
88
|
loadConfig,
|
|
89
|
+
nestsReleaseNotes,
|
|
89
90
|
parseVersionOutput,
|
|
90
91
|
parseVersionOutputFile,
|
|
91
92
|
parseVersionOutputStdin,
|
|
@@ -95,7 +96,8 @@ export {
|
|
|
95
96
|
runPipeline,
|
|
96
97
|
saveAuth,
|
|
97
98
|
versionOutputToChangelogInput,
|
|
99
|
+
writeChangelog,
|
|
98
100
|
writeJson,
|
|
99
|
-
|
|
100
|
-
|
|
101
|
+
writeMonorepoChangelogs,
|
|
102
|
+
writeVersionedNotes
|
|
101
103
|
};
|
package/docs/llm-providers.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# LLM Providers
|
|
2
2
|
|
|
3
|
-
`@releasekit/notes` can use an LLM to
|
|
3
|
+
`@releasekit/notes` can use an LLM to shape release notes: rewrite and group their entries, add a summary, or write prose. `CHANGELOG.md` is always rendered from the commit-derived entries. All LLM configuration lives under `notes.releaseNotes.llm` in `releasekit.config.json`.
|
|
4
4
|
|
|
5
5
|
## Supported Providers
|
|
6
6
|
|
|
@@ -32,7 +32,7 @@ Alternatively, set the provider's environment variable (`OPENAI_API_KEY`, `ANTHR
|
|
|
32
32
|
|
|
33
33
|
## Provider Setup
|
|
34
34
|
|
|
35
|
-
Model names change frequently — check your provider's documentation for the current model IDs. As a general guide: **mini/haiku-tier models** are fast and cheap, suitable for most
|
|
35
|
+
Model names change frequently — check your provider's documentation for the current model IDs. As a general guide: **mini/haiku-tier models** are fast and cheap, suitable for most release-notes enhancement; **standard/sonnet-tier models** produce higher-quality output and are worth the extra cost for public-facing release notes.
|
|
36
36
|
|
|
37
37
|
### OpenAI
|
|
38
38
|
|
|
@@ -128,7 +128,7 @@ Tasks are configured under `llm.tasks`. Multiple tasks can be enabled simultaneo
|
|
|
128
128
|
|
|
129
129
|
### `enhance`
|
|
130
130
|
|
|
131
|
-
Rewrites each
|
|
131
|
+
Rewrites each entry description in the release notes to be clearer and more user-facing.
|
|
132
132
|
|
|
133
133
|
**Input:** `"fix: npe in auth middleware when token is null"`
|
|
134
134
|
**Output:** `"Fix crash during authentication when no token is provided"`
|
|
@@ -143,7 +143,7 @@ Entry descriptions are processed in parallel (default concurrency: `5`). Adjust
|
|
|
143
143
|
{ "concurrency": 3 }
|
|
144
144
|
```
|
|
145
145
|
|
|
146
|
-
When `enhance` and `categorize` are both enabled, the pipeline runs a single combined `enhanceAndCategorize` call — see [Combined enhance + categorize](#combined-enhance--categorize). The combined call also generates `leadIn` phrases, scope assignments, and breaking flags. These drive
|
|
146
|
+
When `enhance` and `categorize` are both enabled, the pipeline runs a single combined `enhanceAndCategorize` call — see [Combined enhance + categorize](#combined-enhance--categorize). The combined call also generates `leadIn` phrases, scope assignments, and breaking flags. These drive breaking change re-routing and `**leadIn**: description` formatting in the built-in renderer, neither of which is available when running `enhance` alone. Routine fixes and bumps receive no `leadIn`.
|
|
147
147
|
|
|
148
148
|
### `summarize`
|
|
149
149
|
|
|
@@ -155,7 +155,7 @@ Generates a one-paragraph summary of the entire release, added to the template c
|
|
|
155
155
|
|
|
156
156
|
### `categorize`
|
|
157
157
|
|
|
158
|
-
Groups entries into user-friendly categories rather than conventional commit types. The result is available in templates as `
|
|
158
|
+
Groups entries into user-friendly categories rather than conventional commit types. The result is available in release-notes templates as `sections`.
|
|
159
159
|
|
|
160
160
|
```json
|
|
161
161
|
{ "tasks": { "categorize": true } }
|
|
@@ -249,7 +249,7 @@ To customise the prompt for the combined call, use the `enhanceAndCategorize` ke
|
|
|
249
249
|
}
|
|
250
250
|
```
|
|
251
251
|
|
|
252
|
-
If you need fully custom output formatting, use the [templates system](./templates.md) instead —
|
|
252
|
+
If you need fully custom output formatting, use the [templates system](./templates.md) instead — release-notes templates get the result after all LLM tasks have run.
|
|
253
253
|
|
|
254
254
|
---
|
|
255
255
|
|
|
@@ -260,6 +260,7 @@ The `--llm-*` flags set LLM options without a config file. Every flag is in the
|
|
|
260
260
|
```bash
|
|
261
261
|
releasekit-notes \
|
|
262
262
|
--input version-output.json \
|
|
263
|
+
--release-notes-dir release-notes \
|
|
263
264
|
--llm-provider anthropic \
|
|
264
265
|
--llm-model claude-haiku-4-5 \
|
|
265
266
|
--llm-tasks enhance,release-notes
|
|
@@ -54,14 +54,12 @@ With `enhance + categorize` enabled, the same commits produce:
|
|
|
54
54
|
|
|
55
55
|
### Breaking
|
|
56
56
|
|
|
57
|
-
- **
|
|
57
|
+
- **API rename**: Rename connect() to initialize()
|
|
58
58
|
|
|
59
59
|
### New
|
|
60
60
|
|
|
61
|
-
**ipc**:
|
|
62
|
-
|
|
63
61
|
- **Deeplink testing**: Add deep link support via triggerDeeplink()
|
|
64
|
-
- Add mock IPC support
|
|
62
|
+
- **ipc**: Add mock IPC support
|
|
65
63
|
|
|
66
64
|
### Fixed
|
|
67
65
|
|
|
@@ -70,6 +68,8 @@ With `enhance + categorize` enabled, the same commits produce:
|
|
|
70
68
|
|
|
71
69
|
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.
|
|
72
70
|
|
|
71
|
+
This applies to release notes only: GitHub release bodies, per-version notes files and the standing PR's notes region. `CHANGELOG.md` always keeps the commit-type form.
|
|
72
|
+
|
|
73
73
|
---
|
|
74
74
|
|
|
75
75
|
## Tasks
|
|
@@ -79,11 +79,11 @@ Four tasks are available. Any combination can be enabled simultaneously.
|
|
|
79
79
|
| Task | What it does | Output location |
|
|
80
80
|
|------|-------------|-----------------|
|
|
81
81
|
| `enhance` | Rewrites entry descriptions to be clear and user-facing | `entries[].description` (replaced in-place) |
|
|
82
|
-
| `categorize` | Groups entries into semantic categories | `
|
|
82
|
+
| `categorize` | Groups entries into semantic categories | `sections` in template context |
|
|
83
83
|
| `summarize` | Generates a 2–3 sentence release summary | `enhanced.summary` in template context |
|
|
84
84
|
| `releaseNotes` | Writes full prose markdown release notes | `enhanced.releaseNotes` / pipeline result |
|
|
85
85
|
|
|
86
|
-
**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
|
|
86
|
+
**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 and LLM-flagged breaking changes in the built-in renderer. Add `summarize` or `releaseNotes` when you want prose output for GitHub releases.
|
|
87
87
|
|
|
88
88
|
> **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.
|
|
89
89
|
|
|
@@ -91,7 +91,7 @@ Four tasks are available. Any combination can be enabled simultaneously.
|
|
|
91
91
|
|
|
92
92
|
## Task: `enhance`
|
|
93
93
|
|
|
94
|
-
Rewrites each
|
|
94
|
+
Rewrites each entry description to be clear, concise, and user-focused.
|
|
95
95
|
|
|
96
96
|
**Input:** `"fix: npe in auth middleware when token is null"`
|
|
97
97
|
**Output:** `"Fix crash during authentication when no token is provided"`
|
|
@@ -108,7 +108,7 @@ Entries are processed in parallel. Control the batch size with `concurrency` (de
|
|
|
108
108
|
|
|
109
109
|
## Task: `categorize`
|
|
110
110
|
|
|
111
|
-
Groups entries into user-friendly categories. The result populates `
|
|
111
|
+
Groups entries into user-friendly categories. The result populates `sections` in the release-notes template context and drives the section layout of the built-in release notes.
|
|
112
112
|
|
|
113
113
|
### Default categories
|
|
114
114
|
|
|
@@ -212,13 +212,11 @@ This is more efficient than two sequential calls and produces richer output. Use
|
|
|
212
212
|
|
|
213
213
|
## Breaking change handling
|
|
214
214
|
|
|
215
|
-
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.
|
|
215
|
+
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. The `Breaking` category comes first unless `categoryOrder` places it.
|
|
216
216
|
|
|
217
217
|
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.
|
|
218
218
|
|
|
219
|
-
|
|
220
|
-
- With `leadIn`: `- **BREAKING** **API rename**: Rename connect() to initialize()`
|
|
221
|
-
- Without `leadIn`: `- **BREAKING** Rename connect() to initialize()`
|
|
219
|
+
The section marks an entry as breaking, so its line has no prefix: `- **API rename**: Rename connect() to initialize()`.
|
|
222
220
|
|
|
223
221
|
---
|
|
224
222
|
|
|
@@ -226,36 +224,16 @@ Rendered format:
|
|
|
226
224
|
|
|
227
225
|
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.
|
|
228
226
|
|
|
229
|
-
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
|
|
227
|
+
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 with just their scope, if any.
|
|
230
228
|
|
|
231
229
|
Rendered format:
|
|
232
230
|
- With `leadIn`: `- **Deeplink testing**: Add deep link support via triggerDeeplink()`
|
|
233
|
-
- Without `leadIn`: `- Add mock IPC support`
|
|
234
|
-
- With `leadIn` + `breaking`: `- **BREAKING** **API rename**: Rename connect() to initialize()`
|
|
231
|
+
- Without `leadIn`: `- **ipc**: Add mock IPC support`, or `- Add mock IPC support` with no scope
|
|
235
232
|
|
|
236
233
|
The `leadIn` value is available in templates as `entry.leadIn` (may be `undefined`).
|
|
237
234
|
|
|
238
235
|
---
|
|
239
236
|
|
|
240
|
-
## Scope grouping
|
|
241
|
-
|
|
242
|
-
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:
|
|
243
|
-
|
|
244
|
-
```markdown
|
|
245
|
-
### New
|
|
246
|
-
|
|
247
|
-
**ipc**:
|
|
248
|
-
|
|
249
|
-
- **Deeplink testing**: Add deep link support via triggerDeeplink()
|
|
250
|
-
- Add mock IPC support
|
|
251
|
-
```
|
|
252
|
-
|
|
253
|
-
A scope that appears on only one entry renders inline: `- **scope**: description`. Entries with no scope render as plain bullets. Both come before the scope groups, so no entry sits under a label it doesn't have.
|
|
254
|
-
|
|
255
|
-
Scope is assigned by the LLM (or inherited from the source commit). Control what scopes are valid with the `scopes` config.
|
|
256
|
-
|
|
257
|
-
---
|
|
258
|
-
|
|
259
237
|
## Scope validation (`scopes`)
|
|
260
238
|
|
|
261
239
|
Controls how the LLM assigns scopes to entries.
|
|
@@ -450,14 +428,12 @@ Note that `links` is a property of `releaseNotes`, not `llm`.
|
|
|
450
428
|
|
|
451
429
|
### Breaking
|
|
452
430
|
|
|
453
|
-
- **
|
|
431
|
+
- **API rename**: Rename connect() to initialize()
|
|
454
432
|
|
|
455
433
|
### New
|
|
456
434
|
|
|
457
|
-
**ipc**:
|
|
458
|
-
|
|
459
435
|
- **Deeplink testing**: Add deep link support via triggerDeeplink()
|
|
460
|
-
- Add mock IPC support
|
|
436
|
+
- **ipc**: Add mock IPC support
|
|
461
437
|
|
|
462
438
|
### Fixed
|
|
463
439
|
|
|
@@ -474,7 +450,7 @@ Note that `links` is a property of `releaseNotes`, not `llm`.
|
|
|
474
450
|
|
|
475
451
|
**What happened:**
|
|
476
452
|
- 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.
|
|
477
|
-
- The
|
|
453
|
+
- The first `feat(ipc)` commit gets a `leadIn` (`"Deeplink testing"`), shown in place of its scope; the second is a routine addition and shows its `ipc` scope.
|
|
478
454
|
- The `fix` commit maps to `Fixed` with no scope or `leadIn` (routine fix).
|
|
479
455
|
- The `chore` commit maps to `Developer` (internal tooling change).
|
|
480
456
|
- The static link from `items` is appended under `### Links`.
|
package/docs/monorepo.md
CHANGED
|
@@ -73,6 +73,47 @@ Custom file name applies to all packages:
|
|
|
73
73
|
|
|
74
74
|
---
|
|
75
75
|
|
|
76
|
+
## Project-wide changes
|
|
77
|
+
|
|
78
|
+
Commits that touch no package outside `version.sharedPackages` are project-wide. In async mode (`sync: false`, no `groups`, more than one package in the run):
|
|
79
|
+
|
|
80
|
+
- **Touching a shared package**, such as a bundled core: every released package's changelog, per-version notes file and release body ends with a `### Project-wide changes` block listing the ones since that package's previous release. A shared package's own block leaves out its own commits.
|
|
81
|
+
- **Touching no package**, such as CI or root tooling: only the root changelog lists them.
|
|
82
|
+
|
|
83
|
+
In those releases, the root changelog lists both kinds once per run, after that run's versions:
|
|
84
|
+
|
|
85
|
+
```markdown
|
|
86
|
+
## [utils@1.1.0] - 2026-03-15
|
|
87
|
+
|
|
88
|
+
### Fixed
|
|
89
|
+
|
|
90
|
+
- Memory leak in event handler
|
|
91
|
+
|
|
92
|
+
## Project-wide changes - 2026-03-15
|
|
93
|
+
|
|
94
|
+
### Fixed
|
|
95
|
+
|
|
96
|
+
- Pin the bundled zod copy
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## Bundled release notes
|
|
102
|
+
|
|
103
|
+
With per-package tags, a releasing package in `version.primaryPackages` gets a section in its release notes and GitHub release body for each of its group-mates and internal dependencies that released changes of their own since the primary's previous release (its previous stable release, if any, for a stable release), in this run or an earlier one. Its internal dependencies are its `dependencies`, `peerDependencies` and cargo path dependencies, followed transitively but not through another primary, which is never bundled.
|
|
104
|
+
|
|
105
|
+
```markdown
|
|
106
|
+
### @myorg/utils 1.1.0 → 1.2.0
|
|
107
|
+
|
|
108
|
+
#### Fixed
|
|
109
|
+
|
|
110
|
+
- Memory leak in event handler
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Only async and grouped releases bundle, and a primary's first release bundles nothing. Each section groups the package's entries by type, Breaking first. In async mode, `version.sharedPackages` are left out, since their changes are already under Project-wide changes. `CHANGELOG.md` stays per package. `githubRelease.skipPackages` still decides whether a bundled package gets its own release.
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
76
117
|
## CLI Flags
|
|
77
118
|
|
|
78
119
|
`--changelog-mode` overrides the configured changelog location. Every flag is in the [CLI reference](../../../docs/cli.md#releasekit-notes-generate).
|