@furystack/yarn-plugin-changelog

A Yarn plugin for automated changelog generation and management in monorepos. It integrates with Yarn's version plugin to generate, validate, and apply changelog entries from version manifests.

Getting Started

Step 1: Install the Plugin

Import the plugin directly from the repository:

yarn plugin import https://raw.githubusercontent.com/furystack/furystack/refs/heads/develop/packages/yarn-plugin-changelog/bundles/%40yarnpkg/plugin-changelog.js

This will automatically add the plugin to your .yarnrc.yml and download it to .yarn/plugins/.

Step 2: Configure Base Refs

Add the changesetBaseRefs setting to your .yarnrc.yml to specify which branches to compare against when checking for version bumps:

changesetBaseRefs:
  - develop
  - origin/develop
  - master
  - origin/master
  - main
  - origin/main

Step 3: Update .gitignore

Add these lines to your .gitignore to track version manifests and changelog drafts:

.yarn/*
!.yarn/patches
!.yarn/plugins
!.yarn/releases
!.yarn/sdks
!.yarn/versions
!.yarn/changelogs

Step 4: Add Scripts to package.json

Add these recommended scripts to your root package.json:

{
  "scripts": {
    "bumpVersions": "yarn version check --interactive",
    "applyReleaseChanges": "yarn version apply --all && yarn changelog apply && yarn prettier --write ."
  }
}

Step 5: CI/CD Setup (Optional)

To enforce changelog entries in your CI pipeline, create these GitHub Actions workflows:

.github/workflows/check-version-bump.yml:

name: Version checks
on:
  push:
    branches-ignore:
      - 'release/**'
      - 'master'
      - 'develop'
jobs:
  check:
    name: Check version bumps
    timeout-minutes: 5
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '24'
      - name: Check version bumps
        run: yarn version check
        env:
          CI: true

.github/workflows/check-changelog.yml:

name: Changelog checks
on:
  push:
    branches-ignore:
      - 'release/**'
      - 'master'
      - 'develop'
  pull_request:
    branches:
      - develop
jobs:
  check:
    name: Check changelog completion
    timeout-minutes: 5
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '24'
      - name: Check changelog entries
        run: yarn changelog check
        env:
          CI: true

Usage

This plugin provides three commands that work together with Yarn's version workflow:

1. Create Changelog Drafts

Generate changelog draft files from version manifests (.yarn/versions/*.yml):

yarn changelog create

This creates draft files in .yarn/changelogs/ with template sections based on the version bump type (patch/minor/major).

Options:

Examples:

# Generate changelog drafts for all version manifests
yarn changelog create

# Regenerate mismatched or invalid changelogs
yarn changelog create --force

# Auto-fill for Dependabot dependency updates
yarn changelog create --dependabot

# With custom message (e.g., from PR title)
yarn changelog create --dependabot -m "Bump lodash from 4.17.20 to 4.17.21"

2. Validate Changelogs

Validate that all changelog entries are complete and match their version manifests:

yarn changelog check

Validates:

• Every release in .yarn/versions/*.yml has a corresponding changelog file
• Major releases have filled "Breaking Changes" sections
• At least one section has content (not just placeholders)
• Version type in changelog matches the manifest

Options:

3. Apply Changelogs

Apply changelog drafts to each package's CHANGELOG.md file:

yarn changelog apply

This command:

• Reads all changelog drafts from .yarn/changelogs/
• Groups entries by package name
• Merges multiple entries for the same package (with deduplication)
• Prepends new entries to each package's CHANGELOG.md
• Deletes processed draft files

Options:

Workflow

A typical release workflow using this plugin:

# 1. Make your changes and commit them

# 2. Bump versions (creates .yarn/versions/*.yml)
yarn version check --interactive

# 3. Generate changelog drafts
yarn changelog create

# 4. Edit the generated drafts in .yarn/changelogs/
#    Fill in the relevant sections with your changes

# 5. Validate changelogs
yarn changelog check

# 6. Apply version changes and changelogs
yarn version apply --all
yarn changelog apply

# 7. Commit and push
git add -A
git commit -m "Release"

Changelog Draft Format

Draft files use a markdown format with conventional changelog sections:

<!-- version-type: minor -->

# @scope/package-name

## 💥 Breaking Changes

(Only for major releases)

## ✨ Features

- Added new feature X

## 🐛 Bug Fixes

- Fixed issue with Y

## 📚 Documentation

## ⚡ Performance

## ♻️ Refactoring

## 🧪 Tests

## 📦 Build

## 👷 CI

## ⬆️ Dependencies

## 🔧 Chores

Directory Structure

.yarn/
├── versions/           # Version manifests (created by yarn version)
│   └── abc123.yml
└── changelogs/         # Changelog drafts (created by this plugin)
    ├── @scope-package-a.abc123.md
    └── @scope-package-b.abc123.md

License

GPL-2.0