CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-semantic-release--changelog

Semantic-release plugin to create or update a changelog file during the release process

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

@semantic-release/changelog

@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.

Package Information

  • Package Name: @semantic-release/changelog
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install @semantic-release/changelog -D
  • Peer Dependencies: semantic-release >=18.0.0
  • Node.js: >=14.17

Core Imports

const { verifyConditions, prepare } = require("@semantic-release/changelog");

For modern module syntax:

import { verifyConditions, prepare } from "@semantic-release/changelog";

Basic Usage

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

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    [
      "@semantic-release/changelog",
      {
        "changelogFile": "CHANGELOG.md",
        "changelogTitle": "# Changelog"
      }
    ],
    [
      "@semantic-release/git",
      {
        "assets": ["CHANGELOG.md"]
      }
    ]
  ]
}

Architecture

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

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

Internal Architecture:

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

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.

Capabilities

Configuration Validation

Validates plugin configuration options to ensure proper setup.

/**
 * Validates plugin configuration during semantic-release's verify phase
 * @param {PluginConfig} pluginConfig - Plugin configuration object
 * @param {Context} context - Semantic-release context with options
 * @returns {Promise<void>} Resolves if valid, throws AggregateError if invalid
 */
async function verifyConditions(pluginConfig, context): Promise<void>;

Changelog Preparation

Creates or updates changelog files with release notes.

/**
 * Creates or updates changelog file during semantic-release's prepare phase
 * @param {PluginConfig} pluginConfig - Plugin configuration object  
 * @param {PrepareContext} context - Semantic-release context with cwd, nextRelease.notes, and logger
 * @returns {Promise<void>} Resolves when changelog is updated
 */
async function prepare(pluginConfig, context): Promise<void>;

Configuration Types

/**
 * Plugin configuration object
 */
interface PluginConfig {
  /** Path to changelog file (default: "CHANGELOG.md") */
  changelogFile?: string;
  /** Title to place at top of changelog file */
  changelogTitle?: string;
}

/**
 * Semantic-release context object for verifyConditions
 */
interface Context {
  /** Release options from semantic-release configuration */
  options: {
    /** Prepare plugin configurations */
    prepare?: Array<string | PluginConfig>;
  };
}

/**
 * Semantic-release context object for prepare phase
 */
interface PrepareContext {
  /** Current working directory */
  cwd: string;
  /** Next release information */
  nextRelease: {
    /** Generated release notes content */
    notes: string;
  };
  /** Semantic-release logger */
  logger: {
    /** Log informational messages */
    log(message: string, ...args: any[]): void;
  };
}

/**
 * Semantic-release error type
 */
interface SemanticReleaseError extends Error {
  /** Error code identifier */
  code: string;
  /** Additional error details */
  details?: string;
}

/**
 * Aggregate error containing multiple validation errors
 */
interface AggregateError extends Error {
  /** Array of individual errors */
  errors: SemanticReleaseError[];
}

Configuration Options

changelogFile

  • Type: string
  • Default: "CHANGELOG.md"
  • Description: File path where the changelog will be created or updated. Must be a non-empty string if provided.

Example:

{
  "changelogFile": "docs/CHANGELOG.md"
}

changelogTitle

  • Type: string
  • Default: undefined
  • 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.

Example:

{
  "changelogTitle": "# Changelog\\n\\nAll notable changes to this project will be documented in this file."
}

Error Handling

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

Error Codes

EINVALIDCHANGELOGFILE: When changelogFile is provided but is not a non-empty string

{
  message: "Invalid `changelogFile` option.",
  details: "The changelogFile option, if defined, must be a non empty String.\n\nYour configuration for the `changelogFile` option is `${changelogFile}`."
}

EINVALIDCHANGELOGTITLE: When changelogTitle is provided but is not a non-empty string

{
  message: "Invalid `changelogTitle` option.",
  details: "The changelogTitle option, if defined, must be a non empty String.\n\nYour configuration for the `changelogTitle` option is `${changelogTitle}`."
}

Validation Logic

The plugin validates configuration using these rules:

  • changelogFile: Must be a non-empty string if provided (defaults to "CHANGELOG.md")
  • changelogTitle: Must be a non-empty string if provided (optional)

Internal Implementation Details

/**
 * Configuration resolution with defaults
 * @param {PluginConfig} pluginConfig - Raw plugin configuration
 * @returns {ResolvedConfig} Configuration with defaults applied
 */
interface ResolvedConfig {
  changelogFile: string; // defaults to "CHANGELOG.md"
  changelogTitle?: string;
}

/**
 * Configuration validators
 */
const VALIDATORS = {
  changelogFile: (value) => isString(value) && value.trim(),
  changelogTitle: (value) => isString(value) && value.trim(),
};

Integration Patterns

With @semantic-release/git

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

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    [
      "@semantic-release/git",
      {
        "assets": ["CHANGELOG.md", "package.json"],
        "message": "chore(release): ${nextRelease.version} [skip ci]\\n\\n${nextRelease.notes}"
      }
    ]
  ]
}

With @semantic-release/npm

Similarly, changelog must run before npm publication:

{
  "plugins": [
    "@semantic-release/commit-analyzer", 
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/npm",
    "@semantic-release/git"
  ]
}

Dynamic Configuration

Configuration can be shared between changelog and git plugins:

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator", 
    [
      "@semantic-release/changelog",
      {
        "changelogFile": "docs/CHANGELOG.md"
      }
    ],
    [
      "@semantic-release/git",
      {
        "assets": ["docs/CHANGELOG.md"]
      }
    ]
  ]
}

Changelog File Behavior

  • New files: If the changelog file doesn't exist, it's created with the release notes
  • Existing files: Release notes are prepended to existing content
  • Title handling: If changelogTitle is configured and the file starts with that title, the title is preserved and content is inserted after it
  • Formatting: Release notes are trimmed and properly spaced with existing content
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@semantic-release/changelog@6.0.x
Publish Source
CLI
Badge
tessl/npm-semantic-release--changelog badge