🧙‍♂️

standard-versionとgit-czを使って、CHANGELOGやバージョンを日本語で管理しよう!

commits9 min read

この記事について

standard-versiongit-cz を使った、バージョン・CHANGELOG管理環境がある程度まとまってきたので、備忘録も兼ねてその環境の構築方法をまとめていきたいと思います🏋️‍♀️

解決したい問題

  • 簡単にバージョン管理したい
  • コミットを簡単にしたい
  • CHANGELOG.mdを日本語で作成したい!
  • コミットメッセージは日本語で!

standard-versionとは?

Conventional Commitsに則ったコミットメッセージから、バージョンを更新したりCHANGELOG.mdを作成することが出来ます。

カスタマイズも結構出来て、自分好みのCHANGELOG.mdを出力することも可能です。
バージョンの決め方も自動でも手動でも決めることが出来るので、CI連携も比較的しやすいと思います。

semantic-releaseとの違いは?

standard-versionと似たようなライブラリで、semantic-releaseと言うのがあります。

これらの違いについて、standard-versionのREADME.mdに説明が書いてあったので、引用します。

semantic-release is described as:

semantic-release automates the whole package release workflow including: determining the next version number, generating the release notes and publishing the package.

While both are based on the same foundation of structured commit messages, standard-version takes a different approach by handling versioning, changelog generation, and git tagging for you without automatic pushing (to GitHub) or publishing (to an npm registry). Use of standard-version only affects your local git repo - it doesn't affect remote resources at all. After you run standard-version, you can review your release state, correct mistakes and follow the release strategy that makes the most sense for your codebase.

We think they are both fantastic tools, and we encourage folks to use semantic-release instead of standard-version if it makes sense for their use-case.

要約
semantic-releaseでは、Githubリポジトリへのプッシュや、npmレジストリへの公開などのパッケージリリースフローを扱うが、standard-versionでは、ローカルのgitリポジトリにのみ変更を与えるので、リモートへの影響がない。

という事らしいです。

なので、semantic-releaseの方が、OSSライブラリ向けな感じがしますね。

その点、standard-versionは変更がローカルのみなので、OSSライブラリではない普通のサービス開発などでも導入しやすいと思います。

git-czとは?

Conventional Commitsに則ったコミットメッセージが書きやすくなるツールです。

git-czでの入力画面

一番の特徴としては、Emojiが扱えるところでしょうか。
Emojiを使うのは好き嫌いが分かれそうですが、コミットメッセージが読み易くなるので筆者は良く使用しています。後、書いていて楽しい😊

また、日本語化も簡単にできるのでお勧めです。

環境構築

これから環境構築を行っていきますが、以下の環境下で構築していく事を想定しています。

要素 バージョン
Node.js v12.18.4
npm v6.14.6

必要モジュールのインストール

package.jsonは既に作成済みである事を想定しています

git-czをインストール

グローバルインストール
$> npm i -g git-cz

git-czは、ローカルインストールすることも可能です。
その場合は、以下のようにします。

git-czをローカルインストール
$> npm install -g commitizen // commitizenをグローバルインストールする必要がある
$> npm install --save-dev git-cz // ローカルインストール

standard-versionをインストール

ローカルインストール
$> npm i --save-dev standard-version

standard-versionは基本的にnpm scriptsを用いて使うため、ローカルインストールで大丈夫です。

設定ファイル

設定ファイルを記述していきます。

git-czの設定

git-czは、changelog.config.jsというファイルで質問の内容や使用するEmojiを変更することが出来ます! なので、今回は質問の文言やコミットメッセージを日本語で表示・入力できるように設定してきます🗾

changelog.config.js
module.exports = {
  // Emojiを非表示にするか
  disableEmoji: false,

  // types一覧
  // typesが設定されているのに、listに登録されてないとgit-czの実行時にエラーを吐く
  // 入れる値は、typesのvalueプロパティで指定した値
  list: [
    'test',
    'feat',
    'fix',
    'chore',
    'docs',
    'refactor',
    'style',
    'ci',
    'perf',
    'config',
    'package',
  ],

  // コミットメッセージの最大文字数
  maxMessageLength: 64,

  // コミットメッセージの最小文字数
  minMessageLength: 3,

  // 質問の種類
  questions: ['type', 'scope', 'subject', 'body', 'breaking', 'issues', 'lerna'],

  // scopesの種類
  // 一つも指定されてない場合、scopeの質問は行われなくなる
  scopes: ['無し', 'API', '機能', '環境構築', '型ファイル'],
  
  // typesの種類を設定する
  types: {
    chore: {
      description: 'ビルドプロセスまたは補助ツールの変更',
      emoji: '🤖',
      value: 'chore',
    },
    ci: {
      description: 'CI関連の変更',
      emoji: '🎡',
      value: 'ci',
    },
    docs: {
      description: 'ドキュメントの変更のみ',
      emoji: '✏️',
      value: 'docs',
    },
    feat: {
      description: '新機能の追加や更新',
      emoji: '🎸',
      value: 'feat',
    },
    fix: {
      description: 'バグ修正',
      emoji: '🐛',
      value: 'fix',
    },
    perf: {
      description: 'パフォーマンスを向上させるコード変更',
      emoji: '⚡️',
      value: 'perf',
    },
    refactor: {
      description: 'リファクタリング',
      emoji: '💡',
      value: 'refactor',
    },
    release: {
      description: 'リリースコミット',
      emoji: '🏹',
      value: 'release',
    },
    style: {
      description: 'マークアップ、ホワイトスペース、フォーマット、セミコロンなどの修正',
      emoji: '💄',
      value: 'style',
    },
    test: {
      description: 'テストの追加・修正',
      emoji: '💍',
      value: 'test',
    },
    
    // 以下、独自で追加したtypes
    config: {
      description: '設定ファイルの追加・修正',
      emoji: '⚙️',
      value: 'config',
    },
    package: {
      description: 'パッケージの追加・更新・削除',
      emoji: '📦',
      value: 'package',
    },
  },
};

ここで注意なのが、scopeの挙動です。
git cz を実行して対話していく中で、デフォルトでは、 scopesプロパティ で指定した値しか入力できません。 これは人によっては凄く不便かもしれませんので、その場合は cz-emoji の方を使ってください。使い方は git-cz と大体同じです。

standard-versionの設定

次に standard-version の設定をしてきますが、環境によって大きく異なるため、この記事ではほとんどデフォルトの設定で記述し、 changelog.config.js で独自に追加した types に対応する設定を行っていきます。

詳しい設定方法は、こちらの公式ドキュメントを参照してください。

.versionrc.json
{
  "types": [
    {
      "type": "chore",
      "section": "ビルドプロセスまたは補助ツールの変更",
      "hidden": false
    },
    {
      "type": "feat",
      "section": "新機能",
      "hidden": false
    },
    {
      "type": "fix",
      "section": "バグ修正",
      "hidden": false
    },
    {
      "type": "docs",
      "section": "ドキュメント",
      "hidden": false
    },
    {
      "type": "style",
      "section": "コードスタイル",
      "hidden": false
    },
    {
      "type": "refactor",
      "section": "リファクタリング",
      "hidden": false
    },
    {
      "type": "perf",
      "section": "パフォーマンスの向上",
      "hidden": false
    },
    {
      "type": "test",
      "section": "テストの追加・修正",
      "hidden": false
    },
    {
      "type": "ci",
      "section": "CI関連",
      "hidden": false
    },
    {
      "type": "config",
      "section": "設定ファイル",
      "hidden": false
    },
    {
      "type": "package",
      "section": "パッケージ",
      "hidden": false
    }
  ],

  // リリースコミットのメッセージを変更する
  "releaseCommitMessageFormat": "chore(release): 🏹{{currentTag}}"
}

package.jsonを設定する

npm scriptsを設定して、npm run ...yarn ... などのコマンドで、CHANGELOG.md の生成とgitのtag付けを出来るように設定します。

standard-versionのREADME.mdには、standard-version -- --release-as ... と言う風に書いてあるのですが、私の環境ではエラーを吐くので、standard-version --release-as ... と言う感じで、--を省いて書いています。

package.json
{
  /* -- 省略 -- */

  "scripts": {
    "release:patch": "standard-version --release-as patch", // 例: v0.0.1 -> v0.0.2
    "release:minor": "standard-version --release-as minor", // 例: v0.0.1 -> v0.1.0
    "release:major": "standard-version --release-as major", // 例: v0.0.1 -> v1.0.0
  },
  
  /* -- 省略 -- */ 
}

使い方

設定が出来たら実際に使って行きます。
基本的には、以下のような流れで使用してきます。

  1. ファイルを変更して git add する
  2. git cz をして対話を開始
  3. 質問に答えていく
  4. 上の事を繰り返す
  5. CHANGELOG.md を生成したくなったらnpm scriptsで定義したリリースコマンドを実行する
  6. リモートにプッシュするなどする

最初にCHANGELOG.mdを生成する場合

CHANGELOG.md を初めて生成する場合は、

yarnで実行
$ npm run standard-version --first-release

または、

yarnで実行
$ yarn standard-version --first-release

を実行して、CHANGELOG.md を生成してください。

その後は、上記の流れで出来ると思います。

終わり

以上で、環境構築は終わりです。お疲れ様でした🙌

この記事の発展形として、Github ActionsなどのCIを用いたリリースフローなどがありますが、これはまた別の機会にでも解説したいと思います👨‍💻

GitHubで編集を提案

Discussion

ログインするとコメントできます