0
# Conventional Changelog Plugin for release-it
1

2
The @release-it/conventional-changelog plugin automates changelog generation and semantic version bumping for release-it. It analyzes conventional commits to determine the appropriate version bump (major, minor, patch) and generates comprehensive changelog files using conventional changelog standards.
3

4
## Package Information
5

6
- **Package Name**: @release-it/conventional-changelog
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES Module)
9
- **Node.js**: ^20.9.0 || >=22.0.0
10
- **Installation**: `npm install --save-dev @release-it/conventional-changelog`
11

12
## Core Imports
13

14
This plugin is typically configured in release-it rather than imported directly. However, for programmatic usage or extension:
15

16
```javascript
17
import ConventionalChangelog from "@release-it/conventional-changelog";
18
```
19

20
For CommonJS environments:
21

22
```javascript
23
const ConventionalChangelog = require("@release-it/conventional-changelog");
24
```
25

26
## Basic Usage
27

28
This plugin is typically configured in the release-it configuration file:
29

30
```json
31
{
32
  "plugins": {
33
    "@release-it/conventional-changelog": {
34
      "preset": {
35
        "name": "angular"
36
      },
37
      "infile": "CHANGELOG.md"
38
    }
39
  }
40
}
41
```
42

43
## Architecture
44

45
The plugin extends the release-it Plugin base class and integrates with the conventional changelog ecosystem:
46

47
- **Plugin Integration**: Extends release-it's Plugin class to provide lifecycle hooks
48
- **Version Bump Analysis**: Uses conventional-recommended-bump to analyze commits and determine version changes
49
- **Changelog Generation**: Leverages conventional-changelog-core for generating formatted changelog content
50
- **File Management**: Handles reading/writing changelog files with proper formatting and headers
51
- **Git Integration**: Works with git tags and commit history to build comprehensive changelogs
52

53
## Capabilities
54

55
### Plugin Class
56

57
Main plugin class that provides conventional changelog functionality for release-it.
58

59
```javascript { .api }
60
class ConventionalChangelog extends Plugin {
61
  /**
62
   * Determines whether to disable the plugin based on options
63
   * @param {Object} options - Plugin configuration options
64
   * @returns {string|null} 'version' if plugin should be disabled, null otherwise
65
   */
66
  static disablePlugin(options);
67

68
  /**
69
   * Processes initial plugin options and sets tag prefix
70
   * @param {Object} options - Configuration options
71
   * @param {string} namespace - Plugin namespace
72
   * @returns {Object} Processed options for namespace
73
   */
74
  getInitialOptions(options, namespace);
75

76
  /**
77
   * Generates changelog for given version
78
   * @param {string} latestVersion - Latest version string
79
   * @returns {Promise<string>} Generated changelog
80
   */
81
  async getChangelog(latestVersion);
82

83
  /**
84
   * Calculates recommended version based on conventional commits
85
   * @param {Object} options - Configuration with increment, latestVersion, isPreRelease, preReleaseId
86
   * @param {string} options.increment - Increment type (major, minor, patch)
87
   * @param {string} options.latestVersion - Latest version string
88
   * @param {boolean} options.isPreRelease - Whether this is a pre-release
89
   * @param {string} options.preReleaseId - Pre-release identifier
90
   * @returns {Promise<string|null>} Recommended version or null
91
   */
92
  async getRecommendedVersion({ increment, latestVersion, isPreRelease, preReleaseId });
93

94
  /**
95
   * Creates a stream for generating changelog content
96
   * @param {Object} rawOptions - Optional raw options for changelog generation (defaults to {})
97
   * @returns {NodeJS.ReadableStream} conventional-changelog stream
98
   */
99
  getChangelogStream(rawOptions = {});
100

101
  /**
102
   * Generates changelog as a string promise
103
   * @param {Object} options - Optional changelog generation options
104
   * @returns {Promise<string>} Generated changelog
105
   */
106
  generateChangelog(options);
107

108
  /**
109
   * Reads existing changelog from infile
110
   * @returns {Promise<string>} Existing changelog content
111
   */
112
  getPreviousChangelog();
113

114
  /**
115
   * Writes generated changelog to file
116
   * @returns {Promise<void>}
117
   */
118
  async writeChangelog();
119

120
  /**
121
   * Gets incremented version if not ignoring recommended bump
122
   * @param {Object} options - Version increment options
123
   * @returns {Promise<string|null>} Incremented version or null
124
   */
125
  getIncrementedVersion(options);
126

127
  /**
128
   * Gets incremented version for CI environments
129
   * @param {Object} options - Version increment options
130
   * @returns {Promise<string|null>} Incremented version or null
131
   */
132
  getIncrementedVersionCI(options);
133

134
  /**
135
   * Sets version context and generates changelog if needed
136
   * @param {string} version - Target version
137
   * @returns {Promise<void>}
138
   */
139
  async bump(version);
140

141
  /**
142
   * Hook executed before release, writes changelog to file
143
   * @returns {Promise<void>}
144
   */
145
  async beforeRelease();
146
}
147
```
148

149
## Configuration Options
150

151
### Core Configuration
152

153
```javascript { .api }
154
interface PluginOptions {
155
  /** Conventional changelog preset configuration */
156
  preset?: PresetConfig | string;
157
  /** Path to changelog file */
158
  infile?: string | false;
159
  /** Header for changelog file (defaults to "# Changelog") */
160
  header?: string;
161
  /** Whether to ignore recommended version bump */
162
  ignoreRecommendedBump?: boolean;
163
  /** Whether to strictly follow semver for pre-releases */
164
  strictSemVer?: boolean;
165
}
166

167
interface PresetConfig {
168
  /** Preset name (angular, conventionalcommits, etc.) */
169
  name: string;
170
  /** Custom commit types configuration */
171
  types?: Array<{
172
    type: string;
173
    section: string;
174
  }>;
175
}
176
```
177

178
### Advanced Configuration
179

180
```javascript { .api }
181
interface AdvancedOptions {
182
  /** Options for commit analysis */
183
  commitsOpts?: Object;
184
  /** Options for git tag handling */
185
  tagOpts?: Object;
186
  /** Custom bump determination function or false to skip */
187
  whatBump?: Function | false;
188
  /** Additional context for changelog generation */
189
  context?: Object;
190
  /** Options for git-raw-commits */
191
  gitRawCommitsOpts?: Object;
192
  /** Options for conventional-commits-parser */
193
  parserOpts?: Object;
194
  /** Options for conventional-changelog-writer */
195
  writerOpts?: Object;
196
  /** Lerna package name for monorepo support */
197
  lernaPackage?: string;
198
  /** Current working directory for git operations */
199
  cwd?: string;
200
  /** Git tag prefix for version tags */
201
  tagPrefix?: string;
202
}
203
```
204

205
## Supported Presets
206

207
The plugin supports multiple conventional changelog presets:
208

209
- `angular` - Angular commit convention
210
- `atom` - Atom editor convention
211
- `codemirror` - CodeMirror convention
212
- `conventionalcommits` - Conventional Commits specification
213
- `ember` - Ember.js convention
214
- `eslint` - ESLint convention
215
- `express` - Express.js convention
216
- `jquery` - jQuery convention
217
- `jscs` - JSCS convention
218
- `jshint` - JSHint convention
219

220
## Integration with release-it
221

222
### Command Line Usage
223

224
Plugin options can be configured via command line:
225

226
```bash
227
# Set changelog file
228
release-it --plugins.@release-it/conventional-changelog.infile=history.md
229

230
# Disable changelog file writing
231
release-it --no-plugins.@release-it/conventional-changelog.infile
232

233
# Use dot notation for nested options
234
release-it --plugins.@release-it/conventional-changelog.preset.name=angular
235
```
236

237
### GitHub Actions Integration
238

239
When using in GitHub Actions, ensure `fetch-depth: 0` is set to access full git history:
240

241
```yaml
242
- uses: actions/checkout@v4
243
  with:
244
    fetch-depth: 0
245
```
246

247
## Dependencies
248

249
### Required Dependencies
250

251
- `concat-stream` ^2.0.0 - Stream concatenation utility
252
- `conventional-changelog` ^6.0.0 - Core conventional changelog functionality
253
- `conventional-recommended-bump` ^10.0.0 - Version bump recommendations
254
- `git-semver-tags` ^8.0.0 - Git semver tag utilities
255
- `semver` ^7.6.3 - Semantic version handling
256

257
### Peer Dependencies
258

259
- `release-it` ^18.0.0 || ^19.0.0 - Required release-it framework
260

261
## Error Handling
262

263
The plugin handles various error conditions gracefully:
264

265
- **Missing git repository**: Throws appropriate errors when git history is unavailable
266
- **Invalid configurations**: Validates preset and option configurations
267
- **File system errors**: Handles missing changelog files by creating them with full history
268
- **Parse errors**: Reports commit parsing issues with detailed error messages