@semantic-release/changelog

What is @semantic-release/changelog?

@semantic-release/changelog is a plugin for semantic-release that updates a changelog file with the changes of the new release. It automates the process of generating and maintaining a changelog based on commit messages, ensuring that the changelog is always up-to-date and consistent with the project's release history.

What are @semantic-release/changelog's main functionalities?

Generate Changelog

This configuration snippet shows how to include the @semantic-release/changelog plugin in your semantic-release setup. It will generate or update the changelog file with the changes of the new release.

{
  "plugins": [
    "@semantic-release/changelog",
    "@semantic-release/git"
  ]
}

Custom Changelog File

This configuration snippet demonstrates how to specify a custom path for the changelog file. In this example, the changelog will be written to 'docs/CHANGELOG.md' instead of the default 'CHANGELOG.md'.

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

Custom Changelog Title

This configuration snippet shows how to set a custom title for the changelog file. The title '# Project Changelog' will be used at the top of the changelog file.

{
  "plugins": [
    [
      "@semantic-release/changelog",
      {
        "changelogTitle": "# Project Changelog"
      }
    ],
    "@semantic-release/git"
  ]
}

Other packages similar to @semantic-release/changelog

conventional-changelog

conventional-changelog is a tool that generates a changelog from git metadata following the Conventional Commits specification. It is highly customizable and can be used as a standalone tool or integrated into build processes. Compared to @semantic-release/changelog, it offers more flexibility in terms of configuration and customization but requires more manual setup.

standard-version

standard-version is a tool that automates versioning and changelog generation based on Conventional Commits. It is simpler to set up compared to @semantic-release/changelog and is often used in projects that do not require the full automation capabilities of semantic-release. It provides a straightforward way to manage releases and changelogs without the need for a CI/CD pipeline.

release-it

release-it is a versatile release automation tool that can handle versioning, changelog generation, and publishing to various package registries. It supports plugins and hooks for customization and can be used with or without semantic-release. Compared to @semantic-release/changelog, release-it offers a more comprehensive set of features for managing the entire release process.

README

@semantic-release/changelog

semantic-release plugin to create or update a changelog file.

Step	Description
verifyConditions	Verify the changelogFile and changelogTitle options configuration.
prepare	Create or update a changelog file in the local project directory with the changelog content created in the generate notes step.

Install

$ npm install @semantic-release/changelog -D

Usage

The plugin can be configured in the semantic-release configuration file:

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

With this example, for each release, a docs/CHANGELOG.md will be created or updated.

Configuration

Options

Options	Description	Default
changelogFile	File path of the changelog.	CHANGELOG.md
changelogTitle	Title of the changelog file (first line of the file).	-

Examples

When used with the @semantic-release/git or @semantic-release/npm plugins the @semantic-release/changelog plugin must be called first in order to update the changelog file so the @semantic-release/git and @semantic-release/npm plugins can include it in the release.

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