conventional-changelog

Installation

SKILL.md

Conventional Changelog

commit メッセージを Conventional Commits 規約で書き、そこから CHANGELOG と semver タグを機械的に生成する運用のガイド。npm / cargo / python / rust / go を横断してツールを選び、手で CHANGELOG を書かずに済ませる。

いつ使うか

新規 repo に release フローを整備する
既存 repo の commit メッセージが揺れていて、CHANGELOG 生成を導入したい
release-please を試したが合わない / 別ツールを検討したい
言語（Rust / Python / Go 等）に合った changelog ツールを探している
tag と CHANGELOG が手運用で壊れがち、自動化したい

Conventional Commits 書式

形式: <type>[optional scope]: <subject>

feat(api): add rate-limit middleware
fix(auth): reject expired tokens before DB lookup
docs: clarify OAuth flow diagram
chore: bump deps

type の一覧と semver 影響

type	semver bump	CHANGELOG 掲載
`feat`	minor	✓ (Added / Features)
`fix`	patch	✓ (Fixed)
`perf`	patch	✓ (Changed)
`refactor`	なし	× (デフォルト)
`docs`	なし	×
`style`	なし	×
`test`	なし	×
`build`	なし	×
`ci`	なし	×
`chore`	なし	×
`revert`	直前に依存	✓

Breaking change（major bump）

2 通り: footer に BREAKING CHANGE: を書く、または type の後に !:

feat(api)!: replace REST endpoint with GraphQL

BREAKING CHANGE: /api/v1/users is removed. Use GraphQL Query.user instead.

両方書くのが丁寧（タイトル見てすぐ分かる + footer で詳細）。

scope

optional だが付けると CHANGELOG が読みやすくなる。monorepo では package 名を scope に:

feat(@pkg/auth): add oauth2 flow
feat(@pkg/billing): stripe migration

scope で release-please の「変更対象パッケージ」も自動判定される（manifest モード）。

subject

小文字で始める（文末ピリオドなし）
命令形（"add X" / "fix Y"、"added" や "fixes" は避ける）
50 文字以内が目安

body / footer

空行を挟んで本文、さらに空行で footer（Closes #123, Co-authored-by: ..., BREAKING CHANGE: ...）。

CHANGELOG.md 形式（Keep a Changelog）

keepachangelog.com に準拠。version 降順、semver、セクションは決まった 6 種:

# Changelog

All notable changes to this project are documented here.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- foo bar

## [1.2.0] - 2026-04-19

### Added

- New `--json` output flag for `foo scan` ([#42](https://github.com/owner/repo/pull/42))

### Changed

- `parse_config` now accepts YAML in addition to TOML

### Fixed

- Crash when config file is empty ([#40](https://github.com/owner/repo/issues/40))

### Deprecated

- `--legacy-mode` flag. Use `--mode=legacy` instead.

### Removed

- `foo bar --old-flag` (deprecated in 1.0.0)

### Security

- Upgrade `openssl` to 3.2.0 to address CVE-2025-XXXXX

## [1.1.0] - 2026-03-01

...

[Unreleased]: https://github.com/owner/repo/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/owner/repo/compare/v1.1.0...v1.2.0

6 セクション:

Added: 新機能
Changed: 既存機能の変更
Deprecated: 削除予定（まだ残っている）
Removed: 削除済み
Fixed: バグ修正
Security: 脆弱性対応

semver タグ運用

tag は v<MAJOR>.<MINOR>.<PATCH> 形式（v1.2.3）。v prefix が主流
pre-release は v1.0.0-beta.1 / v1.0.0-rc.1
git tag -a v1.2.3 -m "Release v1.2.3"（annotated tag）→ git push origin v1.2.3
tag 打ちとデプロイの連動は GitHub Release + Actions の on: release で組む

ツール比較

ツール	対応言語	方式	CHANGELOG 生成	version bump	主な利点	弱点
release-please	npm / python / rust / go / java / php / ruby	Release PR が自動で作られる	○	○ (PR merge で tag)	monorepo 対応、Google 製で安定	PR ベースで学習コスト
changesets	npm 専用	`changeset add` で手動記録	○	○	monorepo + 柔軟 (npm workspaces)	commit 駆動ではない
conventional-changelog-cli	言語非依存（コマンド）	commit から 1 発生成	○	×	軽量、既存 CHANGELOG に追記	tag / bump は別で手動
standard-version (deprecated)	npm	commit → bump + CHANGELOG	○	○	シンプル	メンテ停止、release-please に移行推奨
git-cliff	言語非依存（Rust 製）	TOML 設定で高カスタマイズ	○	×	高速、テンプレ柔軟、Rust エコシステムに好まれる	tag / bump は別
towncrier	Python	news fragment を PR 毎に書く	○	×	fragment で merge 時の衝突回避	独特なワークフロー
auto (intuit/auto)	複数	label ベース + CI 統合	○	○	GitHub label 駆動	独自 label 規約

一言推奨

npm 単一 package で自動化したい → release-please
npm monorepo → release-please（manifest モード）or changesets（細かい制御）
Rust → git-cliff
Python → towncrier（or release-please）
Go / 汎用 → git-cliff or release-please
CHANGELOG だけ生成したい（tag 管理は手動） → conventional-changelog-cli or git-cliff

release-please セットアップ（最推奨パス）

npm project で新規導入する場合:

// release-please-config.json
{
  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
  "release-type": "node",
  "packages": {
    ".": { "package-name": "my-pkg", "changelog-path": "CHANGELOG.md" }
  },
  "include-v-in-tag": true,
  "bump-minor-pre-major": true
}

// .release-please-manifest.json
{ ".": "0.0.0" }

# .github/workflows/release-please.yml
name: release-please
on:
  push:
    branches: [main]
permissions:
  contents: write
  pull-requests: write
jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: googleapis/release-please-action@v4
        with:
          config-file: release-please-config.json
          manifest-file: .release-please-manifest.json

commit を conventional 規約で書いて main に push すると、自動で「Release PR」が作られる。merge すると tag + GitHub Release + CHANGELOG 更新が走る。

publish 連動 workflow の 2 形態:

形態	trigger	利点	弱点
同一 workflow 内で job 分離（`needs: release-please` + `if: outputs.release_created`）	`push: main`	1 ファイルで完結、release-please の outputs を直接参照、概観しやすい	release-please job が失敗すると publish も巻き込まれる、責務が混ざる
別 workflow（`on: release`）	`release: { types: [published] }`	関心の分離、手動 release でも publish が走る、再実行が独立	secrets / permissions を 2 箇所に書く、release-please outputs が使えない

選択指針: 単一 package・単一 publish 先（npm のみ）なら同一 workflow が簡潔。複数 publish 先（npm + GitHub Container Registry など）や手動 release も許容するなら on: release 別 workflow。OIDC Trusted Publishing を使う場合は id-token: write 権限を publish job 側にだけ付ければよく、どちらでも成立する。

詳細は npm-release skill（ローカル管理）の publish フロー参照。

Pre-release (beta / rc) 段階リリース

breaking change を含む v2.0.0 を beta → rc → 正式版の順に出したいとき。release-please の prerelease / prerelease-type フラグを使う:

// release-please-config.json
{
  "packages": {
    ".": {
      "package-name": "my-pkg",
      "prerelease": true,
      "prerelease-type": "beta"
    }
  }
}

フロー:

prerelease-type: "beta" で commit を積む → v2.0.0-beta.1 が切られる
追加 commit で v2.0.0-beta.2 / beta.3 ... が積み重なる
RC 昇格時: config を "prerelease-type": "rc" に書き換え → v2.0.0-rc.1
正式リリース時: "prerelease": false（or フィールド削除）→ v2.0.0

CHANGELOG の書き方: release-please は 各 beta/rc で独立セクションを確定 させる（Keep a Changelog の [Unreleased] に貯める方式ではない）。[2.0.0-beta.1] / [2.0.0-beta.2] / [2.0.0-rc.1] / [2.0.0] がすべて残る。2.0.0 正式版のセクションには期間内の全 feat! / BREAKING CHANGE が集約される。

Monorepo + `workspace:*` の相互作用

pnpm workspace で @org/core, @org/ui, @org/cli を持ち、@org/ui と @org/cli が @org/core に依存するとき:

// release-please-config.json
{
  "plugins": [
    { "type": "node-workspace", "updatePeerDependencies": true }
  ],
  "packages": {
    "packages/core": {
      "release-type": "node",
      "package-name": "@org/core",
      "include-component-in-tag": true
    },
    "packages/ui": {
      "release-type": "node",
      "package-name": "@org/ui",
      "include-component-in-tag": true
    },
    "packages/cli": {
      "release-type": "node",
      "package-name": "@org/cli",
      "include-component-in-tag": true
    }
  },
  "separate-pull-requests": false,
  "include-v-in-tag": true
}

include-component-in-tag: true → tag 名は @org/core-v2.0.0 のように component 名を含む（monorepo 衝突回避）
node-workspace plugin → @org/core 側の bump を検出して @org/ui / @org/cli の dependencies."@org/core" を書き換え、両者を patch bump として PR に追加
updatePeerDependencies: true → peer 依存も同様に書き換え（library 側で必要）
separate-pull-requests: false → 全 package の bump を 1 本の Release PR に集約

commit scope に package 名を入れる運用:

feat(@org/core): add streaming parser
fix(@org/ui): button focus ring on safari
feat(@org/cli)!: rename --config to --profile

scope で変更対象を自動判定。該当 package の CHANGELOG にだけエントリが書かれる。

workspace:* 置換の仕組み: @org/ui/package.json で "@org/core": "workspace:*" と書いても publish 時に pnpm が自動で ^<実バージョン> に置換する。release-please 側は bump 時に workspace:* のまま source を弄らない。この前提でちょうど辻褄が合う（pnpm 側で workspace:^ → ^同major、workspace:~ → ~同minor）。

git-cliff セットアップ（Rust / 汎用）

cargo install git-cliff
# or
brew install git-cliff

# cliff.toml
[changelog]
header = "# Changelog\n"
body = """
{% if version %}## [{{ version }}] - {{ timestamp | date(format="%Y-%m-%d") }}{% endif %}
{% for group, commits in commits | group_by(attribute="group") %}
### {{ group | upper_first }}
{% for commit in commits %}
- {{ commit.message | upper_first }} ({{ commit.id | truncate(length=7, end="") }})
{% endfor %}
{% endfor %}
"""

[git]
conventional_commits = true
filter_unconventional = true       # 既存の規約違反 commit を CHANGELOG から除外
protect_breaking_commits = true
commit_parsers = [
  { message = "^feat",     group = "Added" },
  { message = "^fix",      group = "Fixed" },
  { message = "^perf",     group = "Changed" },
  { message = "^refactor", group = "Changed" },
  { message = "^deprecat", group = "Deprecated" },
  { message = "^remove",   group = "Removed" },
  { message = "^security", group = "Security" },
  { message = "^revert",   group = "Reverted" },
  { message = "^(docs|style|test|build|ci|chore)", skip = true },
  { message = ".*",        skip = true },   # 規約違反一括除外（遡及書き換えしない）
]
tag_pattern = "v[0-9]*"
sort_commits = "newest"

Rust 向け運用で cargo-release と併用する場合、cargo-release が Cargo.toml の version bump と tag 打ちを担い、git-cliff は CHANGELOG 生成に専念する（疎結合）。release-please のような PR ベース自動 bump を入れない理由でもある。

git-cliff --output CHANGELOG.md            # 全履歴から再生成
git-cliff --unreleased --prepend CHANGELOG.md  # 未リリース分だけ上に追記
git-cliff --tag v1.2.0 --output CHANGELOG.md   # 特定 tag 向けに生成

cargo-release との結線（具体例）

Cargo.toml の [package.metadata.release] に hook を仕込む。cargo release <level> を叩くと、bump → CHANGELOG 生成 → commit → tag → push が一連で走る:

# Cargo.toml
[package.metadata.release]
# version bump 後・commit 前に git-cliff で CHANGELOG を更新
pre-release-hook = ["git", "cliff", "--tag", "v{{version}}", "--unreleased", "--prepend", "CHANGELOG.md"]
# tag は cargo-release 側が打つ
tag-name = "v{{version}}"
# release commit に CHANGELOG.md を含める
pre-release-commit-message = "chore(release): v{{version}}"

順序:

cargo release minor --execute → Cargo.toml の version bump
pre-release-hook で git cliff が次 version の [Unreleased] を [v0.2.0] - 2026-04-19 に確定し CHANGELOG.md を更新
cargo-release が Cargo.toml + CHANGELOG.md を release commit にまとめる
tag-name で v0.2.0 を annotated tag として打つ
cargo publish + git push --tags

注意: git-cliff 側の [changelog.bump] セクション（features_always_bump_minor 等）は git-cliff 自身が bump 判断する独自機能で、cargo-release と併用するときは使わない（bump 主体は cargo-release）。<level> (patch / minor / major) は人間が選ぶ前提。