0
# @semantic-release/release-notes-generator
1

2
A semantic-release plugin that generates changelog content using conventional-changelog. This plugin analyzes commit messages following conventional commit standards and produces formatted release notes for software releases.
3

4
## Package Information
5

6
- **Package Name**: @semantic-release/release-notes-generator
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES modules)
9
- **Installation**: `npm install @semantic-release/release-notes-generator`
10

11
## Core Imports
12

13
```javascript
14
import { generateNotes } from "@semantic-release/release-notes-generator";
15
import loadChangelogConfig from "@semantic-release/release-notes-generator/lib/load-changelog-config.js";
16
import HOSTS_CONFIG from "@semantic-release/release-notes-generator/lib/hosts-config.js";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const { generateNotes } = require("@semantic-release/release-notes-generator");
23
const loadChangelogConfig = require("@semantic-release/release-notes-generator/lib/load-changelog-config.js").default;
24
const HOSTS_CONFIG = require("@semantic-release/release-notes-generator/lib/hosts-config.js").default;
25
```
26

27
## Basic Usage
28

29
This plugin is designed to be used within the semantic-release ecosystem:
30

31
```json
32
{
33
  "plugins": [
34
    "@semantic-release/commit-analyzer",
35
    [
36
      "@semantic-release/release-notes-generator",
37
      {
38
        "preset": "angular",
39
        "parserOpts": {
40
          "noteKeywords": ["BREAKING CHANGE", "BREAKING CHANGES", "BREAKING"]
41
        },
42
        "writerOpts": {
43
          "commitsSort": ["subject", "scope"]
44
        }
45
      }
46
    ]
47
  ]
48
}
49
```
50

51
Direct programmatic usage:
52

53
```javascript
54
import { generateNotes } from "@semantic-release/release-notes-generator";
55

56
const pluginConfig = {
57
  preset: "angular",
58
  parserOpts: {},
59
  writerOpts: {}
60
};
61

62
const context = {
63
  commits: [
64
    { hash: "abc123", message: "feat(auth): add login functionality" },
65
    { hash: "def456", message: "fix(ui): correct button alignment" }
66
  ],
67
  lastRelease: { gitTag: "v1.0.0" },
68
  nextRelease: { gitTag: "v2.0.0", version: "2.0.0" },
69
  options: { repositoryUrl: "https://github.com/owner/repo" },
70
  cwd: process.cwd()
71
};
72

73
const changelog = await generateNotes(pluginConfig, context);
74
console.log(changelog);
75
```
76

77
## Architecture
78

79
The plugin operates through several key components:
80

81
- **Main Function**: `generateNotes` processes commits and generates changelog content
82
- **Configuration Loader**: Dynamically loads conventional-changelog presets and custom configurations
83
- **Host Configuration**: Provides platform-specific settings for GitHub, GitLab, and Bitbucket
84
- **Commit Processing**: Parses commits using conventional-commits-parser and filters reverted commits
85
- **Changelog Generation**: Uses conventional-changelog-writer to produce formatted output
86

87
## Capabilities
88

89
### Generate Release Notes
90

91
The primary functionality for generating changelog content from commits.
92

93
```javascript { .api }
94
/**
95
 * Generate the changelog for all the commits in context.commits
96
 * @param {Object} pluginConfig - The plugin configuration
97
 * @param {String} [pluginConfig.preset] - conventional-changelog preset ('angular', 'atom', 'codemirror', 'ember', 'eslint', 'express', 'jquery', 'jscs', 'jshint')
98
 * @param {String} [pluginConfig.config] - Requireable npm package with a custom conventional-changelog preset
99
 * @param {Object} [pluginConfig.parserOpts] - Additional conventional-changelog-parser options that will overwrite ones loaded by preset or config
100
 * @param {Object} [pluginConfig.writerOpts] - Additional conventional-changelog-writer options that will overwrite ones loaded by preset or config
101
 * @param {Object} [pluginConfig.presetConfig] - Configuration for the preset
102
 * @param {Object} [pluginConfig.host] - Host configuration overrides
103
 * @param {Boolean} [pluginConfig.linkCompare] - Enable/disable compare links
104
 * @param {Boolean} [pluginConfig.linkReferences] - Enable/disable reference links
105
 * @param {Object} [pluginConfig.commit] - Commit configuration overrides
106
 * @param {Object} [pluginConfig.issue] - Issue configuration overrides
107
 * @param {Object} context - The semantic-release context
108
 * @param {Array<Object>} context.commits - The commits to analyze
109
 * @param {Object} context.lastRelease - The last release with gitHead and gitTag
110
 * @param {Object} context.nextRelease - The next release with gitHead, version, and gitTag
111
 * @param {Object} context.options - Contains repositoryUrl and other options
112
 * @param {String} context.cwd - Current working directory
113
 * @returns {Promise<String>} The changelog content as HTML/markdown string
114
 */
115
async function generateNotes(pluginConfig, context);
116
```
117

118
### Load Changelog Configuration
119

120
Internal function for loading conventional-changelog configuration from presets or custom packages.
121

122
```javascript { .api }
123
/**
124
 * Load conventional-changelog-parser options. Handle presets that return either a Promise<Array> or a Promise<Function>
125
 * @param {Object} pluginConfig - The plugin configuration
126
 * @param {String} [pluginConfig.preset] - conventional-changelog preset ('angular', 'atom', 'codemirror', 'ember', 'eslint', 'express', 'jquery', 'jscs', 'jshint')
127
 * @param {String} [pluginConfig.config] - Requireable npm package with a custom conventional-changelog preset
128
 * @param {Object} [pluginConfig.parserOpts] - Additional conventional-changelog-parser options that will overwrite ones loaded by preset or config
129
 * @param {Object} [pluginConfig.writerOpts] - Additional conventional-changelog-writer options that will overwrite ones loaded by preset or config
130
 * @param {Object} [pluginConfig.presetConfig] - Configuration for the preset
131
 * @param {Object} context - The semantic-release context
132
 * @param {Array<Object>} context.commits - The commits to analyze
133
 * @param {String} context.cwd - The current working directory
134
 * @returns {Promise<Object>} A Promise that resolves to the conventional-changelog-core config with parserOpts and writerOpts
135
 */
136
async function loadChangelogConfig(pluginConfig, context);
137
```
138

139
### Host Configuration Constants
140

141
Pre-defined host configurations for popular Git hosting platforms.
142

143
```javascript { .api }
144
/**
145
 * Host configurations for different Git hosting platforms
146
 */
147
const HOSTS_CONFIG = {
148
  github: {
149
    hostname: "github.com",
150
    issue: "issues",
151
    commit: "commit",
152
    referenceActions: ["close", "closes", "closed", "fix", "fixes", "fixed", "resolve", "resolves", "resolved"],
153
    issuePrefixes: ["#", "gh-"]
154
  },
155
  bitbucket: {
156
    hostname: "bitbucket.org", 
157
    issue: "issue",
158
    commit: "commits",
159
    referenceActions: ["close", "closes", "closed", "closing", "fix", "fixes", "fixed", "fixing", "resolve", "resolves", "resolved", "resolving"],
160
    issuePrefixes: ["#"]
161
  },
162
  gitlab: {
163
    hostname: "gitlab.com",
164
    issue: "issues", 
165
    commit: "commit",
166
    referenceActions: ["close", "closes", "closed", "closing", "fix", "fixes", "fixed", "fixing"],
167
    issuePrefixes: ["#"]
168
  },
169
  default: {
170
    issue: "issues",
171
    commit: "commit", 
172
    referenceActions: ["close", "closes", "closed", "closing", "fix", "fixes", "fixed", "fixing", "resolve", "resolves", "resolved", "resolving"],
173
    issuePrefixes: ["#", "gh-"]
174
  }
175
};
176
```
177

178
### Configuration Objects
179

180
Configuration structures used by the plugin.
181

182
```javascript { .api }
183
interface PluginConfig {
184
  /** Conventional-changelog preset name */
185
  preset?: "angular" | "atom" | "codemirror" | "ember" | "eslint" | "express" | "jquery" | "jscs" | "jshint";
186
  /** Custom conventional-changelog preset package name */
187
  config?: string;
188
  /** Additional parser options */
189
  parserOpts?: {
190
    /** Keywords that indicate breaking changes */
191
    noteKeywords?: string[];
192
    /** Other parser configuration options */
193
    [key: string]: any;
194
  };
195
  /** Additional writer options */
196
  writerOpts?: {
197
    /** Sort order for commits */
198
    commitsSort?: string[];
199
    /** Other writer configuration options */
200
    [key: string]: any;
201
  };
202
  /** Configuration for the preset */
203
  presetConfig?: Record<string, any>;
204
  /** Host configuration overrides */
205
  host?: Record<string, any>;
206
  /** Enable/disable compare links */
207
  linkCompare?: boolean;
208
  /** Enable/disable reference links */
209
  linkReferences?: boolean;
210
  /** Commit configuration overrides */
211
  commit?: Record<string, any>;
212
  /** Issue configuration overrides */
213
  issue?: Record<string, any>;
214
}
215

216
interface SemanticReleaseContext {
217
  /** Array of commit objects to analyze */
218
  commits: Array<{
219
    /** Commit hash */
220
    hash: string;
221
    /** Commit message */
222
    message: string;
223
    /** Author information with name, email, and date */
224
    author?: {
225
      name?: string;
226
      email?: string;
227
      date?: string;
228
    };
229
    /** Committer information with name, email, and date */
230
    committer?: {
231
      name?: string;
232
      email?: string;
233
      date?: string;
234
    };
235
    /** Parsed commit type (feat, fix, etc.) - added by conventional-commits-parser */
236
    type?: string;
237
    /** Parsed commit scope - added by conventional-commits-parser */
238
    scope?: string;
239
    /** Parsed commit subject - added by conventional-commits-parser */
240
    subject?: string;
241
    /** Parsed commit body - added by conventional-commits-parser */
242
    body?: string;
243
    /** Parsed commit footer - added by conventional-commits-parser */
244
    footer?: string;
245
    /** Breaking change notes - added by conventional-commits-parser */
246
    notes?: Array<{
247
      title: string;
248
      text: string;
249
    }>;
250
    /** Issue references - added by conventional-commits-parser */
251
    references?: Array<{
252
      action?: string;
253
      owner?: string;
254
      repository?: string;
255
      issue: string;
256
      raw: string;
257
      prefix: string;
258
    }>;
259
    /** Whether this is a revert commit - added by conventional-commits-parser */
260
    revert?: Record<string, any> | null;
261
    /** Other commit properties */
262
    [key: string]: any;
263
  }>;
264
  /** Last release information */
265
  lastRelease: {
266
    /** Git commit hash of last release */
267
    gitHead?: string;
268
    /** Git tag of last release */
269
    gitTag?: string;
270
    /** Version of last release */
271
    version?: string;
272
  };
273
  /** Next release information */
274
  nextRelease: {
275
    /** Git commit hash of next release */
276
    gitHead?: string;
277
    /** Git tag of next release */
278
    gitTag?: string;
279
    /** Version of next release */
280
    version: string;
281
  };
282
  /** Semantic-release options */
283
  options: {
284
    /** Repository URL */
285
    repositoryUrl: string;
286
    /** Other semantic-release options */
287
    [key: string]: any;
288
  };
289
  /** Current working directory */
290
  cwd: string;
291
}
292
```
293

294
### Host Configuration
295

296
Platform-specific configuration for different Git hosting services.
297

298
```javascript { .api }
299
interface HostConfig {
300
  /** Platform hostname */
301
  hostname: string;
302
  /** Issue path segment for URLs */
303
  issue: string;
304
  /** Commit path segment for URLs */
305
  commit: string;
306
  /** Keywords that reference/close issues */
307
  referenceActions: string[];
308
  /** Prefixes that indicate issue references */
309
  issuePrefixes: string[];
310
}
311

312
interface HostsConfiguration {
313
  github: HostConfig;
314
  bitbucket: HostConfig;
315
  gitlab: HostConfig;
316
  default: HostConfig;
317
}
318
```
319

320
### Wrapper Modules
321

322
Internal wrapper modules that provide compatibility with conventional-changelog packages.
323

324
```javascript { .api }
325
/**
326
 * Wrapper for conventional-changelog-writer that exports the writeChangelogStream function
327
 * Located at: wrappers/conventional-changelog-writer.js
328
 */
329
import { writeChangelogStream as writer } from 'conventional-changelog-writer';
330
export default writer;
331
```
332

333
## Configuration Examples
334

335
### Angular Preset (Default)
336

337
```json
338
{
339
  "preset": "angular",
340
  "parserOpts": {
341
    "noteKeywords": ["BREAKING CHANGE", "BREAKING CHANGES", "BREAKING"]
342
  },
343
  "writerOpts": {
344
    "commitsSort": ["subject", "scope"]
345
  }
346
}
347
```
348

349
### Custom Preset
350

351
```json
352
{
353
  "config": "conventional-changelog-eslint",
354
  "parserOpts": {
355
    "headerPattern": "/^(\\w*)(?:\\(([\\w\\$\\.\\-\\* ]*)\\))?: (.*)$/",
356
    "headerCorrespondence": ["type", "scope", "subject"]
357
  }
358
}
359
```
360

361
### Host Configuration Override
362

363
```json
364
{
365
  "preset": "angular",
366
  "host": "https://custom-git-host.com",
367
  "linkCompare": true,
368
  "linkReferences": true,
369
  "commit": {
370
    "linkPath": "commits"
371
  },
372
  "issue": {
373
    "linkPath": "issues"
374
  }
375
}
376
```
377

378
## Error Handling
379

380
The plugin handles various error scenarios:
381

382
- **Empty commit messages**: Silently skipped with debug logging
383
- **Invalid preset/config**: Throws error if preset or config package cannot be loaded
384
- **Malformed repository URL**: Attempts to parse and normalize various URL formats
385
- **Missing context properties**: Uses reasonable defaults where possible
386

387
Common issues:
388

389
- Ensure `repositoryUrl` is properly formatted
390
- Verify preset packages are installed if using custom presets
391
- Check that commits array contains objects with `hash` and `message` properties
392
- Confirm `lastRelease` and `nextRelease` objects have appropriate properties