Conventional Changelog Core

Conventional Changelog Core provides the core functionality for generating conventional changelogs from git commit metadata. It serves as the foundation for the conventional-changelog ecosystem, offering a streaming API that processes git commits according to conventional commit standards and generates structured changelog entries through a configurable pipeline.

Package Information

• Package Name: conventional-changelog-core
• Package Type: npm
• Language: JavaScript (ES Module)
• Installation: npm install conventional-changelog-core

Core Imports

import conventionalChangelog from "conventional-changelog-core";

For older CommonJS environments (not officially supported in v9.0.0+):

const conventionalChangelog = require("conventional-changelog-core");

Basic Usage

import conventionalChangelog from "conventional-changelog-core";

// Basic changelog generation
conventionalChangelog()
  .pipe(process.stdout);

// With options
conventionalChangelog({
  releaseCount: 1,
  skipUnstable: false
})
  .pipe(process.stdout);

// Full configuration
conventionalChangelog(
  { releaseCount: 2, append: false },
  {},                    // context
  {},                    // gitRawCommitsOpts
  {},                    // parserOpts
  {}                     // writerOpts
)
  .pipe(process.stdout);

Architecture

Conventional Changelog Core implements a streaming pipeline that processes git commits through several stages:

1. Git Raw Commits: Retrieves raw commit data from git repository
2. Conventional Commits Parser: Parses commit messages according to conventional commit format
3. Transform: Applies custom transformations to parsed commits
4. Changelog Writer: Formats the final changelog output

The entire process is handled through Node.js streams, allowing for efficient processing of large repositories and enabling custom processing through stream manipulation.

Capabilities

Main Changelog Generation

The primary function creates a readable stream that generates conventional changelog content from git commit history.

function conventionalChangelog(
  options?: Options,
  context?: Context,
  gitRawCommitsOpts?: GitRawCommitsOptions,
  parserOpts?: ParserOptions,
  writerOpts?: WriterOptions,
  gitRawExecOpts?: GitRawExecOptions
): Readable;

Returns: A Node.js Readable stream containing the formatted changelog content.

Configuration Options

Options Object

interface Options {
  config?: Promise<Config> | (() => Config) | Config;
  pkg?: {
    path?: string;
    transform?: (pkg: any) => any;
  };
  append?: boolean;
  releaseCount?: number;
  skipUnstable?: boolean;
  debug?: (message: string) => void;
  warn?: (message: string) => void;
  transform?: (commit: any, cb: (err: Error | null, commit?: any) => void) => void;
  outputUnreleased?: boolean;
  lernaPackage?: string;
  tagPrefix?: string;
  cwd?: string;
}

Option Details:

• config: Configuration object or function providing default values for other parameters
• pkg.path: Path to package.json file (defaults to closest package.json)
• pkg.transform: Function to transform package.json data before processing
• append: Whether to append changelog to existing data (default: false)
• releaseCount: Number of releases to generate changelog for (default: 1, use 0 for all releases)
• skipUnstable: Skip unstable release tags like x.x.x-rc (default: false)
• debug: Debug logging function
• warn: Warning logging function (defaults to debug function)
• transform: Custom commit transformation function applied after parsing
• outputUnreleased: Include unreleased changes in output
• lernaPackage: Specific package name for Lerna monorepo processing
• tagPrefix: Git tag prefix to consider during comparison
• cwd: Working directory for git operations

Context Object

interface Context {
  version?: string;
  host?: string;
  owner?: string;
  repository?: string;
  repoUrl?: string;
  gitSemverTags?: string[];  // Read-only
  previousTag?: string;
  currentTag?: string;
  packageData?: any;         // Read-only
  linkCompare?: boolean;
  resetChangelog?: boolean;
  [key: string]: any;
}

Context Details:

• version: Package version (extracted from package.json if not provided)
• host: Repository host URL (extracted from package.json repository URL)
• owner: Repository owner (extracted from repository URL)
• repository: Repository name (extracted from repository URL)
• repoUrl: Full repository URL
• gitSemverTags: Array of all semantic version tags found in repository (read-only)
• previousTag: Previous semver tag or first commit hash
• currentTag: Current semver tag or 'v' + version
• packageData: Parsed package.json data (read-only)
• linkCompare: Whether to include comparison links between tags
• resetChangelog: Reset changelog generation from beginning (ignores tag-based ranges)

Git Raw Commits Options

interface GitRawCommitsOptions {
  format?: string;
  from?: string;
  reverse?: boolean;
  debug?: (message: string) => void;
  merges?: boolean;
  cwd?: string;
  [key: string]: any;
}

Git Options Details:

• format: Git log format string (default: '%B%n-hash-%n%H%n-gitTags-%n%d%n-committerDate-%n%ci')
• from: Starting commit or tag for changelog generation
• reverse: Reverse commit order (default: true if options.append is true)
• debug: Debug function for git operations
• merges: Include merge commits (default: false)
• cwd: Working directory for git commands

Parser Options

interface ParserOptions {
  warn?: (message: string) => void;
  referenceActions?: string[];
  issuePrefixes?: string[];
  [key: string]: any;
}

Parser Details:

• warn: Warning function for parsing issues
• referenceActions: Array of actions that reference issues (e.g., ['close', 'closes', 'fix', 'fixes'])
• issuePrefixes: Array of prefixes for issue references (e.g., ['#', 'gh-'])

Writer Options

interface WriterOptions {
  finalizeContext?: (
    context: Context,
    writerOpts: WriterOptions,
    filteredCommits: any[],
    keyCommit: any,
    originalCommits: any[]
  ) => Context;
  debug?: (message: string) => void;
  reverse?: boolean;
  doFlush?: boolean;
  includeDetails?: boolean;
  [key: string]: any;
}

Writer Details:

• finalizeContext: Function to finalize context before writing
• debug: Debug function for writer operations
• reverse: Reverse output order (defaults to options.append)
• doFlush: Flush unreleased content (defaults to options.outputUnreleased)
• includeDetails: Include detailed commit information in output

Git Raw Exec Options

interface GitRawExecOptions {
  cwd?: string;
  [key: string]: any;
}

Host Configuration

The package includes built-in configuration for major git hosting providers:

interface HostConfig {
  issue: string;
  commit: string;
  referenceActions: string[];
  issuePrefixes: string[];
}

Supported Hosts:

• GitHub: { issue: "issues", commit: "commit", referenceActions: ["close", "closes", "closed", "fix", "fixes", "fixed", "resolve", "resolves", "resolved"], issuePrefixes: ["#", "gh-"] }
• GitLab: { issue: "issues", commit: "commit", referenceActions: ["close", "closes", "closed", "closing", "fix", "fixes", "fixed", "fixing"], issuePrefixes: ["#"] }
• Bitbucket: { issue: "issue", commit: "commits", referenceActions: ["close", "closes", "closed", "closing", "fix", "fixes", "fixed", "fixing", "resolve", "resolves", "resolved", "resolving"], issuePrefixes: ["#"] }

Error Handling

The function returns a readable stream that emits standard Node.js stream events. Error handling should be done through stream event listeners:

const stream = conventionalChangelog(options);

stream.on('error', (error) => {
  console.error('Changelog generation failed:', error.message);
});

stream.on('data', (chunk) => {
  // Process changelog chunk
});

stream.on('end', () => {
  console.log('Changelog generation completed');
});

Common Error Sources:

• Git repository not found or invalid
• Git command execution failures
• Commit parsing errors
• Transform function errors
• Writer formatting errors

Advanced Usage Examples

Custom Transform Function

import conventionalChangelog from "conventional-changelog-core";

const options = {
  transform: (commit, cb) => {
    // Add custom fields to commits
    if (commit.type === 'feat') {
      commit.isFeature = true;
    }
    
    // Format commit date
    if (commit.committerDate) {
      commit.committerDate = new Date(commit.committerDate).toISOString().split('T')[0];
    }
    
    cb(null, commit);
  }
};

conventionalChangelog(options)
  .pipe(process.stdout);

Lerna Monorepo Usage

import conventionalChangelog from "conventional-changelog-core";

const options = {
  lernaPackage: 'my-package',
  tagPrefix: 'my-package@',
  cwd: './packages/my-package'
};

conventionalChangelog(options)
  .pipe(process.stdout);

Custom Package.json Processing

import conventionalChangelog from "conventional-changelog-core";

const options = {
  pkg: {
    path: './custom-package.json',
    transform: (pkg) => {
      // Add 'v' prefix to version
      return {
        ...pkg,
        version: pkg.version.startsWith('v') ? pkg.version : `v${pkg.version}`
      };
    }
  }
};

conventionalChangelog(options)
  .pipe(process.stdout);