Introduction to Conventional Changelog

Conventional Changelog is a tool that helps developers create consistent and easy-to-read changelog files based on commit messages. This streamlines the release process and ensures better communication with team members and users. In this guide, we’ll explain some of the most useful APIs provided by Conventional Changelog and give examples to help you integrate it into your project.

Basic Usage

To get started with Conventional Changelog, you need to install it via npm:

  
    npm install -g conventional-changelog-cli
  

You can then generate a changelog for your project:

  
    conventional-changelog -p angular -i CHANGELOG.md -s
  

API Examples

Create a New Changelog

  
    const conventionalChangelog = require('conventional-changelog');
    conventionalChangelog({
      preset: 'angular'
    })
    .pipe(fs.createWriteStream('CHANGELOG.md'));
  

Updating an Existing Changelog

  
    const conventionalChangelog = require('conventional-changelog');
    const fs = require('fs');
    conventionalChangelog({
      preset: 'angular'
    })
    .pipe(fs.createWriteStream('CHANGELOG.md', { flags: 'a' }));
  

Customizing Output

  
    const conventionalChangelog = require('conventional-changelog');
    const fs = require('fs');
    conventionalChangelog({
      preset: 'angular',
      releaseCount: 2
    })
    .pipe(fs.createWriteStream('CHANGELOG.md'));
  

Using a Custom Template

  
    const conventionalChangelogWriter = require('conventional-changelog-writer');
    const template = fs.readFileSync('template.hbs', 'utf-8');
    const stream = source.pipe(conventionalChangelogWriter({
      preset: 'angular',
      mainTemplate: template
    }));
    stream.pipe(fs.createWriteStream('CHANGELOG.md'));
  

Example Application

Here’s an example setup of a Node.js application that uses Conventional Changelog for versioning:

  
    const conventionalChangelog = require('conventional-changelog');
    const fs = require('fs');
    
    // Generate initial changelog
    conventionalChangelog({
      preset: 'angular'
    })
    .pipe(fs.createWriteStream('CHANGELOG.md'));
    
    // Simulate updates and append to changelog on subsequent releases
    function updateChangelog() {
      conventionalChangelog({
        preset: 'angular'
      })
      .pipe(fs.createWriteStream('CHANGELOG.md', { flags: 'a' }));
    }
    
    // Example usage after commits
    updateChangelog();
  

With this setup, your project will maintain a well-organized changelog, making it easier for everyone to track changes and updates.

Hash: b37728fba2476b9f490edb4a5cece7650614b7ce2bbcb2f6610337769f1e5b2b