0
# @semantic-release/changelog
1

2
@semantic-release/changelog is a semantic-release plugin that automates the creation and updating of changelog files during the release process. It integrates seamlessly with the semantic-release workflow to generate changelog entries based on commit messages and release notes.
3

4
## Package Information
5

6
- **Package Name**: @semantic-release/changelog
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install @semantic-release/changelog -D`
10
- **Peer Dependencies**: semantic-release >=18.0.0
11
- **Node.js**: >=14.17
12

13
## Core Imports
14

15
```javascript
16
const { verifyConditions, prepare } = require("@semantic-release/changelog");
17
```
18

19
For modern module syntax:
20

21
```javascript
22
import { verifyConditions, prepare } from "@semantic-release/changelog";
23
```
24

25
## Basic Usage
26

27
This plugin is configured as part of a semantic-release configuration file:
28

29
```json
30
{
31
  "plugins": [
32
    "@semantic-release/commit-analyzer",
33
    "@semantic-release/release-notes-generator",
34
    [
35
      "@semantic-release/changelog",
36
      {
37
        "changelogFile": "CHANGELOG.md",
38
        "changelogTitle": "# Changelog"
39
      }
40
    ],
41
    [
42
      "@semantic-release/git",
43
      {
44
        "assets": ["CHANGELOG.md"]
45
      }
46
    ]
47
  ]
48
}
49
```
50

51
## Architecture
52

53
The plugin operates through semantic-release's lifecycle hooks:
54

55
1. **verifyConditions**: Validates plugin configuration during the verify phase
56
2. **prepare**: Creates or updates the changelog file during the prepare phase
57

58
**Internal Architecture:**
59
- Maintains internal verification state to avoid duplicate validation
60
- Uses configuration resolution with defaults (changelogFile: "CHANGELOG.md") 
61
- Validates configuration against defined rules using lodash utility functions
62
- Creates or updates changelog files using fs-extra for reliable file operations
63
- Handles existing changelog content preservation and title management
64

65
The plugin uses release notes generated by semantic-release's notes generation step and either creates a new changelog file or prepends new content to an existing one.
66

67
## Capabilities
68

69
### Configuration Validation
70

71
Validates plugin configuration options to ensure proper setup.
72

73
```javascript { .api }
74
/**
75
 * Validates plugin configuration during semantic-release's verify phase
76
 * @param {PluginConfig} pluginConfig - Plugin configuration object
77
 * @param {Context} context - Semantic-release context with options
78
 * @returns {Promise<void>} Resolves if valid, throws AggregateError if invalid
79
 */
80
async function verifyConditions(pluginConfig, context): Promise<void>;
81
```
82

83
### Changelog Preparation
84

85
Creates or updates changelog files with release notes.
86

87
```javascript { .api }
88
/**
89
 * Creates or updates changelog file during semantic-release's prepare phase
90
 * @param {PluginConfig} pluginConfig - Plugin configuration object  
91
 * @param {PrepareContext} context - Semantic-release context with cwd, nextRelease.notes, and logger
92
 * @returns {Promise<void>} Resolves when changelog is updated
93
 */
94
async function prepare(pluginConfig, context): Promise<void>;
95
```
96

97
## Configuration Types
98

99
```javascript { .api }
100
/**
101
 * Plugin configuration object
102
 */
103
interface PluginConfig {
104
  /** Path to changelog file (default: "CHANGELOG.md") */
105
  changelogFile?: string;
106
  /** Title to place at top of changelog file */
107
  changelogTitle?: string;
108
}
109

110
/**
111
 * Semantic-release context object for verifyConditions
112
 */
113
interface Context {
114
  /** Release options from semantic-release configuration */
115
  options: {
116
    /** Prepare plugin configurations */
117
    prepare?: Array<string | PluginConfig>;
118
  };
119
}
120

121
/**
122
 * Semantic-release context object for prepare phase
123
 */
124
interface PrepareContext {
125
  /** Current working directory */
126
  cwd: string;
127
  /** Next release information */
128
  nextRelease: {
129
    /** Generated release notes content */
130
    notes: string;
131
  };
132
  /** Semantic-release logger */
133
  logger: {
134
    /** Log informational messages */
135
    log(message: string, ...args: any[]): void;
136
  };
137
}
138

139
/**
140
 * Semantic-release error type
141
 */
142
interface SemanticReleaseError extends Error {
143
  /** Error code identifier */
144
  code: string;
145
  /** Additional error details */
146
  details?: string;
147
}
148

149
/**
150
 * Aggregate error containing multiple validation errors
151
 */
152
interface AggregateError extends Error {
153
  /** Array of individual errors */
154
  errors: SemanticReleaseError[];
155
}
156
```
157

158
## Configuration Options
159

160
### changelogFile
161

162
- **Type**: `string`
163
- **Default**: `"CHANGELOG.md"`
164
- **Description**: File path where the changelog will be created or updated. Must be a non-empty string if provided.
165

166
**Example**:
167
```json
168
{
169
  "changelogFile": "docs/CHANGELOG.md"
170
}
171
```
172

173
### changelogTitle
174

175
- **Type**: `string`
176
- **Default**: `undefined`
177
- **Description**: Optional title to place at the beginning of the changelog file. If provided, must be a non-empty string. Typically includes markdown heading syntax.
178

179
**Example**:
180
```json
181
{
182
  "changelogTitle": "# Changelog\\n\\nAll notable changes to this project will be documented in this file."
183
}
184
```
185

186
## Error Handling
187

188
The plugin throws `SemanticReleaseError` instances for configuration validation failures. Multiple validation errors are collected and thrown as an `AggregateError`.
189

190
### Error Codes
191

192
**EINVALIDCHANGELOGFILE**: When `changelogFile` is provided but is not a non-empty string
193
```javascript
194
{
195
  message: "Invalid `changelogFile` option.",
196
  details: "The changelogFile option, if defined, must be a non empty String.\n\nYour configuration for the `changelogFile` option is `${changelogFile}`."
197
}
198
```
199

200
**EINVALIDCHANGELOGTITLE**: When `changelogTitle` is provided but is not a non-empty string  
201
```javascript
202
{
203
  message: "Invalid `changelogTitle` option.",
204
  details: "The changelogTitle option, if defined, must be a non empty String.\n\nYour configuration for the `changelogTitle` option is `${changelogTitle}`."
205
}
206
```
207

208
### Validation Logic
209

210
The plugin validates configuration using these rules:
211
- `changelogFile`: Must be a non-empty string if provided (defaults to "CHANGELOG.md")  
212
- `changelogTitle`: Must be a non-empty string if provided (optional)
213

214
### Internal Implementation Details
215

216
```javascript { .api }
217
/**
218
 * Configuration resolution with defaults
219
 * @param {PluginConfig} pluginConfig - Raw plugin configuration
220
 * @returns {ResolvedConfig} Configuration with defaults applied
221
 */
222
interface ResolvedConfig {
223
  changelogFile: string; // defaults to "CHANGELOG.md"
224
  changelogTitle?: string;
225
}
226

227
/**
228
 * Configuration validators
229
 */
230
const VALIDATORS = {
231
  changelogFile: (value) => isString(value) && value.trim(),
232
  changelogTitle: (value) => isString(value) && value.trim(),
233
};
234
```
235

236
## Integration Patterns
237

238
### With @semantic-release/git
239

240
The changelog plugin must run before @semantic-release/git to include changelog changes in commits:
241

242
```json
243
{
244
  "plugins": [
245
    "@semantic-release/commit-analyzer",
246
    "@semantic-release/release-notes-generator",
247
    "@semantic-release/changelog",
248
    [
249
      "@semantic-release/git",
250
      {
251
        "assets": ["CHANGELOG.md", "package.json"],
252
        "message": "chore(release): ${nextRelease.version} [skip ci]\\n\\n${nextRelease.notes}"
253
      }
254
    ]
255
  ]
256
}
257
```
258

259
### With @semantic-release/npm
260

261
Similarly, changelog must run before npm publication:
262

263
```json
264
{
265
  "plugins": [
266
    "@semantic-release/commit-analyzer", 
267
    "@semantic-release/release-notes-generator",
268
    "@semantic-release/changelog",
269
    "@semantic-release/npm",
270
    "@semantic-release/git"
271
  ]
272
}
273
```
274

275
### Dynamic Configuration
276

277
Configuration can be shared between changelog and git plugins:
278

279
```json
280
{
281
  "plugins": [
282
    "@semantic-release/commit-analyzer",
283
    "@semantic-release/release-notes-generator", 
284
    [
285
      "@semantic-release/changelog",
286
      {
287
        "changelogFile": "docs/CHANGELOG.md"
288
      }
289
    ],
290
    [
291
      "@semantic-release/git",
292
      {
293
        "assets": ["docs/CHANGELOG.md"]
294
      }
295
    ]
296
  ]
297
}
298
```
299

300
## Changelog File Behavior
301

302
- **New files**: If the changelog file doesn't exist, it's created with the release notes
303
- **Existing files**: Release notes are prepended to existing content
304
- **Title handling**: If `changelogTitle` is configured and the file starts with that title, the title is preserved and content is inserted after it
305
- **Formatting**: Release notes are trimmed and properly spaced with existing content