changesets

Changesets

概要

Changesets は、マルチパッケージリポジトリに特化したバージョン管理および変更履歴管理ツールです。コントリビューターは changeset ファイルを使って各変更の semver への影響（major／minor／patch）を宣言し、Changesets はそれらを集約して、バージョンの更新、変更履歴の更新、パッケージの公開を連携した単一のリリースとして行います。

使用するケース： モノレポのバージョン管理、自動変更履歴生成、複数パッケージの連携リリース、CI 主導の公開、プレリリース／スナップショットのワークフロー。

使用しないケース： npm への公開を行わない単一ファイルのプロジェクト、コミットメッセージベースのバージョン管理（semantic-release）を使用するプロジェクト、npm レジストリを使わずに手動でバージョン管理を行うプロジェクト、すべてのリリースを単一のメンテナーが PR での協業なしに管理するプロジェクト。

仕組み

1. コントリビューターが、影響を受けるパッケージ、バンプの種類、概要を宣言する changeset ファイルを追加します
2. PR で、changeset ファイルをコード変更と一緒にコミットします
3. リリースの準備ができたら、changeset version が未処理の changeset をすべて適用し、バージョンと変更履歴を更新します
4. changeset publish が更新されたパッケージを npm に公開し、git タグを作成します
5. CI では、公式 GitHub Action が自動更新される「Version Packages」PR を通じて、手順 3〜4 を自動化します

主な概念

• Changeset ファイル — .changeset/ 内にある Markdown ファイルです。影響を受けるパッケージ、バンプの種類（major／minor／patch）、変更履歴に表示される人間が読める概要を宣言します
• バージョンコマンド — 未処理の changeset ファイルをすべて適用し、最終的なバージョンのバンプを計算して、package.json のバージョンを更新し、CHANGELOG.md のエントリーを生成し、内部依存関係の範囲を更新します
• 公開コマンド — 更新されたパッケージを npm に公開し、git タグを作成します。version の直後に、コミットを挟まずに実行する必要があります
• リンクされたパッケージ — リリース時に同じ最上位のバンプの種類を共有しつつ、独立したバージョン番号を維持するパッケージです
• 固定パッケージ — グループ内で常に完全に同じバージョン番号を共有するパッケージです
• プレリリースモード — 安定版リリース前のテスト用に、version がプレリリースバージョン（例：1.0.0-beta.0）を生成するモードです
• スナップショットリリース — メインのリリース系列に影響を与えずに、その場限りのテストを行うための一時的な 0.0.0-timestamp バージョンです

設定クイックリファレンス

オプション	デフォルト	説明
changelog	"@changesets/cli/changelog"	変更履歴ジェネレーターのパッケージ。無効にする場合は false を指定します
commit	false	version コマンドと add コマンドで自動コミットします
access	"restricted"	npm の公開アクセス設定です。スコープ付きパッケージを公開するには "public" を設定します
baseBranch	"main"	変更検出に使用するブランチ
linked	[]	最上位のバンプの種類を共有するパッケージのグループ
fixed	[]	完全に同じバージョンを共有するパッケージのグループ
ignore	[]	changeset によるバージョン管理から除外するパッケージ
updateInternalDependencies	"patch"	依存側をバンプするタイミングです。"patch" または "minor" を指定します
privatePackages	{ version: true, tag: false }	"private": true のパッケージに対するバージョン／タグの動作

クイックリファレンス

パターン	コマンド／設定	主なポイント
初期化	npx @changesets/cli init	.changeset/ フォルダーを設定ファイルとともに作成します
変更セットを追加	npx @changesets/cli add	対象パッケージとバージョン更新の種類を対話形式で指定します
空の変更セットを追加	npx @changesets/cli add --empty	バージョン更新が必要なパッケージがないことを宣言します（CI を通過するため）
パッケージのバージョン更新	npx @changesets/cli version	変更セットを処理し、バージョンを更新して、変更履歴を更新します
パッケージを公開	npx @changesets/cli publish	npm に公開し、Git タグを作成します
ステータスを確認	npx @changesets/cli status	保留中の変更セットを一覧表示します。変更セットのない変更がある場合は終了コード 1 で終了します
ブランチ以降のステータス	npx @changesets/cli status --since=main	main から分岐した後の変更のみを確認します
プレリリースに移行	npx @changesets/cli pre enter <tag>	プレリリースモード（beta、alpha、rc、next）を有効にします
プレリリースを終了	npx @changesets/cli pre exit	通常のバージョン管理モードに戻します
スナップショットバージョン	npx @changesets/cli version --snapshot	テスト用に 0.0.0-タイムスタンプ形式のバージョンを作成します
スナップショットを公開	npx @changesets/cli publish --tag canary --no-git-tag	最新の dist-tag を上書きせずにスナップショットを公開します
パッケージをリンク	"linked": [["pkg-a", "pkg-b"]] in config	パッケージ間で最も高いバージョン更新の種類を共有します
パッケージを固定	"fixed": [["pkg-*"]] in config	パッケージ間で完全に同じバージョン番号を共有します
パッケージを除外	"ignore": ["pkg-internal"] in config	変更セットによるバージョン管理からパッケージを除外します
公開アクセス	"access": "public" in config	スコープ付きパッケージを公開する場合に必要です
GitHub の変更履歴	"changelog": ["@changesets/changelog-github", ...]	PR へのリンクとコントリビューターのクレジットを追加します
自動コミット	"commit": true in config	version コマンドと add コマンドで変更を自動コミットします
内部依存関係	"updateInternalDependencies": "patch" in config	内部依存パッケージのバージョンを更新するタイミングを制御します

よくある間違い

間違い	正しいパターン
version と publish の間にコミットする	version の直後に、間にコミットを挟まず publish を実行する
パッケージの変更がない PR で --empty を忘れる	CI チェックを通過するには npx @changesets/cli add --empty を使用する
パッケージ間でバージョンを完全に一致させる必要があるのに linked を使う	同一バージョンには fixed を使用する。linked で共有されるのは更新幅のみ
公開パッケージに access: "restricted" を設定する	公開 npm パッケージでは設定に access: "public" を設定する
CI のチェックアウトに fetch-depth: 0 を含めない	changeset の検出には Git の履歴全体が必要です
先にビルドせずに publish を実行する	changeset publish の前に必ずビルドステップを実行する
main ブランチでプレリリースモードに入る	通常のリリースを妨げないよう、プレリリースには専用ブランチを使用する
他のパッケージが依存しているパッケージを無視する	無視されたパッケージは更新されず、依存先に問題が生じます。使用は控えてください
デフォルトのタグでスナップショットを公開する	latest の dist-tag を上書きしないよう、必ず --tag フラグを使用する
CI 環境で NPM_TOKEN を設定しない	自動公開には GITHUB_TOKEN と NPM_TOKEN の両方が必要です
CI でアクションを使わずに changeset publish を使用する	公式の changesets/action は、2 モードのワークフローを正しく処理します
生成された CHANGELOG.md を手動で編集する	代わりに changeset ファイルを編集してください。version 実行時に変更履歴が再生成されます

委任

• CI パイプラインのデバッグ：リポジトリ固有のワークフローの調査には Explore エージェントを使用します
• npm 公開の問題：公開やレジストリ認証の失敗のデバッグには Task エージェントを使用します

turborepo スキルが利用可能な場合は、ビルドのオーケストレーション、タスクのキャッシュ、CI の最適化を委任してください。 pnpm-workspace スキルが利用可能な場合は、ワークスペースの設定、依存関係のリンク、カタログ、Docker デプロイを委任してください。エンドツーエンドのリリースパイプラインについては、モノレポ統合リファレンスを参照してください。

参考資料

• 基本的なワークフロー：changeset の追加、バージョン管理、公開、CI 統合
• モノレポの設定：構成、リンクされたパッケージ、固定バージョン管理、無視パターン
• CI の自動化：GitHub Actions、自動 PR、スナップショットリリース、プレリリースチャネル